youys
/
DocNet
Not watched
1
0
Fork 0
Code
Releases 14 Wiki Activity
Issues 0 Pull Requests 0 Datasets Model Cloudbrain
You can not select more than 25 topics Topics must start with a chinese character,a letter or number, can include dashes ('-') and can be up to 35 characters long.
Tree: bee8b325aa
Branches Tags
${ item.name }
Create branch ${ searchTerm }
from 'bee8b325aa'
${ noResults }
DocNet/docnetjson.htm

222 lines
18 kB
Raw Blame History 

  1. <!DOCTYPE html>

  2. <!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->

  3. <!--[if gt IE 8]><!-->

  4. <html class="no-js" lang="en">

  5. <!--<![endif]-->

  6. <head>

  7.     <meta charset="utf-8">

  8.     <meta http-equiv="X-UA-Compatible" content="IE=edge">

  9.     <meta name="viewport" content="width=device-width, initial-scale=1.0">

  10. 

  11.     <title>Site configuration with the docnet.json file - DocNet Documentation</title>

  12.     <link rel="shortcut icon" href="favicon.ico">

  13.     <link rel="stylesheet" href="css/theme.css" type="text/css" />

  14.     <link rel="stylesheet" href="css/theme_colors.css" type="text/css" />

  15.     <link rel="stylesheet" href="css/styles/vs.css">

  16.     <link rel="stylesheet" href="css/font-awesome.4.5.0.min.css">

  17. </head>

  18. <body role="document">

  19.     <div class="grid-for-nav">

  20.         <nav data-toggle="nav-shift" class="nav-side stickynav">

  21.             <div class="side-nav-search">

  22.                 <a href="index.htm"><i class="fa fa-home"></i> DocNet Documentation</a>

  23.                 <div role="search">

  24.                     <form id="search-form" class="form" action="Docnet_search.htm" method="get">

  25.                         <input type="text" name="q" placeholder="Search docs" />

  26.                     </form>

  27.                 </div>

  28.             </div>

  29.             <div class="menu menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">

  30. <ul>

  31. <li class="tocentry"><a href="index.htm">Home</a>

  32. </li>

  33. 

  34. <li class="tocentry"><a href="usage.htm">Usage</a>

  35. </li>

  36. <li class="tocentry">

  37. <ul>

  38. <li><span class="navigationgroup"><i class="fa fa-caret-down"></i> <a href="Configuration.htm">Configuration</a></span></li>

  39. <li class="tocentry current"><a class="current" href="docnetjson.htm">Site configuration with the docnet.json file</a>

  40. <ul class="currentrelative">

  41. <li class="tocentry"><a href="#name">Name</a></li>

  42. 

  43. <li class="tocentry"><a href="#source">Source</a></li>

  44. 

  45. <li class="tocentry"><a href="#destination">Destination</a></li>

  46. 

  47. <li class="tocentry"><a href="#includesource">IncludeSource</a></li>

  48. 

  49. <li class="tocentry"><a href="#theme">Theme</a></li>

  50. 

  51. <li class="tocentry"><a href="#sourcefolderstocopy">SourceFoldersToCopy</a></li>

  52. 

  53. <li class="tocentry"><a href="#convertlocallinks">ConvertLocalLinks</a></li>

  54. 

  55. <li class="tocentry"><a href="#pathspecification">PathSpecification</a></li>

  56. 

  57. <li class="tocentry"><a href="#urlformatting">UrlFormatting</a></li>

  58. 

  59. <li class="tocentry"><a href="#maxlevelintoc">MaxLevelInToC</a></li>

  60. 

  61. <li class="tocentry"><a href="#stripindexhtm">StripIndexHtm</a></li>

  62. 

  63. <li class="tocentry"><a href="#footer">Footer</a></li>

  64. 

  65. <li class="tocentry"><a href="#startingpagename">StartingPageName</a></li>

  66. 

  67. <li class="tocentry"><a href="#pages">Pages</a></li>

  68. 

  69. <li class="tocentry"><a href="#levels-without-index-defined">Levels without __index defined</a></li>

  70. 

  71. <li class="tocentry"><a href="#use-of-wildcard-inclusions">Use of wildcard inclusions</a></li>

  72. 

  73. 

  74. 

  75. </ul>

  76. <li class="tocentry"><a href="h2leveldiscovery.htm">Automatic H2 level ToC entry discovery</a>

  77. </li>

  78. <li class="tocentry"><a href="notfound.htm">Not found (404) page</a>

  79. </li>

  80. 

  81. </ul>

  82. </li>

  83. <li class="tocentry">

  84. <span class="navigationgroup"><i class="fa fa-caret-right"></i> <a href="Authoringcontent.htm">Authoring content</a></span>

  85. </li>

  86. <li class="tocentry"><a href="search.htm">Search</a>

  87. </li>

  88. <li class="tocentry"><a href="acknowledgements.htm">Acknowledgements</a>

  89. </li>

  90. <li class="tocentry"><a href="license.htm">License</a>

  91. </li>

  92. </ul>

  93. 				<div class="toc-footer">

  94. 					<span class="text-small">

  95. 						<hr/>

  96. 						<a href="https://github.com/FransBouma/DocNet" target="_blank">Made with <i class="fa fa-github"></i> DocNet</a>

  97. 					</span>

  98. 				</div>	

  99. 			</div>

  100.             &nbsp;

  101.         </nav>

  102.         <section data-toggle="nav-shift" class="nav-content-wrap">

  103.             <nav class="nav-top" role="navigation" aria-label="top navigation">

  104.                 <i data-toggle="nav-top" class="fa fa-bars"></i>

  105.                 <a href="index.htm">DocNet Documentation</a>

  106.             </nav>

  107.             <div class="nav-content">

  108.                 <div role="navigation" aria-label="breadcrumbs navigation">

  109.                     <div class="breadcrumbs">

  110. <ul><li><a href="index.htm">Home</a></li> / <li><a href="Configuration.htm">Configuration</a></li> / <li><a href="docnetjson.htm">Site configuration with the docnet.json file</a></li></ul>

  111. 					

  112.                     </div>

  113.                     <hr />

  114.                 </div>

  115.                 <div role="main">

  116.                     <div class="section">

  117. <h1 id="the-configuration-file-docnet.json">The configuration file: 'docnet.json'<a class="headerlink" href="#the-configuration-file-docnet.json" title="Permalink to this headline"><i class="fa fa-link" aria-hidden="true"></i></a></h1>

  118. <p>DocNet uses a json file to determine what to do in what form. The format is straight forward and described below</p>

  119. <pre><code class="json">{

  120.     &quot;Name&quot; : &quot;name of site&quot;,

  121.     &quot;Source&quot; : &quot;sourcefolder&quot;,

  122.     &quot;Destination&quot; : &quot;destinationfolder&quot;,

  123.     &quot;IncludeSource&quot;: &quot;includefolder&quot;,

  124.     &quot;Theme&quot; : &quot;themefolder&quot;,

  125.     &quot;SourceFoldersToCopy&quot; : [&quot;folder1&quot;, &quot;foldern&quot;],

  126.     &quot;Footer&quot; : &quot;footer text or HTML&quot;,

  127.     &quot;StartingPageName&quot; : &quot;Home&quot;,

  128.     &quot;ConvertLocalLinks&quot; : &quot;true&quot; | &quot;false&quot;,

  129.     &quot;PathSpecification&quot; : &quot;Full&quot; | &quot;Relative&quot; | &quot;RelativeAsFolder&quot;,

  130.     &quot;UrlFormatting&quot; : &quot;None&quot; | &quot;Strip&quot; | &quot;Dashes&quot;,

  131.     &quot;MaxLevelInToC&quot; : &quot;3&quot;,

  132.     &quot;StripIndexHtm&quot; : &quot;true&quot; | &quot;false&quot;,

  133.     &quot;Pages&quot; : 

  134.     {

  135.         &quot;__index&quot; : &quot;index.md&quot;,

  136.         &quot;Title Page 1&quot; : &quot;filename_page1.md&quot;, 

  137.         &quot;Title Page 2&quot; : &quot;filename_page2.md&quot;,

  138.         &quot;Sub Header 1&quot; : 

  139.         {

  140.             &quot;__index&quot; : &quot;index.md&quot;,

  141.             &quot;Title Page 3&quot; : &quot;filename_page3.md&quot;,

  142.             &quot;Title Page 4&quot; : &quot;filename_page4.md&quot;

  143.         },

  144.         &quot;Auto generated&quot; : &quot;reference/**&quot;

  145.     }

  146. }

  147. </code></pre>

  148. 

  149. <p>The order in which the pages are specified is the order in which they'll appear in the navigation. </p>

  150. <h3 id="name">Name<a class="headerlink" href="#name" title="Permalink to this headline"><i class="fa fa-link" aria-hidden="true"></i></a></h3>

  151. <p>Specifies the name of the site to generate. </p>

  152. <h3 id="source">Source<a class="headerlink" href="#source" title="Permalink to this headline"><i class="fa fa-link" aria-hidden="true"></i></a></h3>

  153. <p>Specifies the root of the tree of folders in which markdown files are expected. <code>sourcefolder</code> can be a relative path or an absolute path and is used as the root folder for filenames specified in <code>Pages</code>.</p>

  154. <h3 id="destination">Destination<a class="headerlink" href="#destination" title="Permalink to this headline"><i class="fa fa-link" aria-hidden="true"></i></a></h3>

  155. <p>Specifies the folder where the output will be written to (.htm files). The output will be written to this folder only, all files from subfolders in <code>Source</code> will be written to the folder specified in <code>Destination</code>. with the same structure as the <em>navigation</em> in <code>Pages</code>. <code>destinationfolder</code> can be a relative path or an absolute path.</p>

  156. <h3 id="includesource">IncludeSource<a class="headerlink" href="#includesource" title="Permalink to this headline"><i class="fa fa-link" aria-hidden="true"></i></a></h3>

  157. <p>Specifies the folder where the files specified to be included using <a href="markdownextensions.htm#include-files">@@include directives</a> are located. If <code>IncludeSource</code> isn't specified, the value <code>Includes</code> is assumed. </p>

  158. <h3 id="theme">Theme<a class="headerlink" href="#theme" title="Permalink to this headline"><i class="fa fa-link" aria-hidden="true"></i></a></h3>

  159. <p>Specifies the folder within the <code>Themes</code> folder in the folder the <code>docnet</code> executable is located which is used as the theme for the pages to generate. <code>Docnet</code> expects a file called <code>PageTemplate.htm</code> within the specified <code>Theme</code> folder, which contains the HTML which is used as the wrapper file for the HTML generated from the markdown. It has to contain a couple of marker, which are described later in this document. If <code>Theme</code> isn't specified, <code>Default</code> is assumed.</p>

  160. <h3 id="sourcefolderstocopy">SourceFoldersToCopy<a class="headerlink" href="#sourcefolderstocopy" title="Permalink to this headline"><i class="fa fa-link" aria-hidden="true"></i></a></h3>

  161. <p>This is an optional directive with, if specified, one or more folder names relative to <code>Source</code>, which contain files to copy to the <code>Destination</code> folder. E.g. image files used in the markdown files, located in an <code>Images</code> folder can be copied this way to the output folder reliably. All folders specified are copied recursively.</p>

  162. <h3 id="convertlocallinks">ConvertLocalLinks<a class="headerlink" href="#convertlocallinks" title="Permalink to this headline"><i class="fa fa-link" aria-hidden="true"></i></a></h3>

  163. <p>This is an optional directive which, if specified and set to <code>&quot;true&quot;</code>, will make DocNet convert all local links to <code>.md</code> suffixed files into <code>.htm</code> files. Example: <code>(local link)[somemarkdownfile.md]</code> will be converted to <code>&lt;a href=&quot;somemarkdownfile.htm&quot;&gt;local link&lt;/a&gt;</code>. Non-local urls are not converted. Default: <code>&quot;false&quot;</code>. </p>

  164. <h3 id="pathspecification">PathSpecification<a class="headerlink" href="#pathspecification" title="Permalink to this headline"><i class="fa fa-link" aria-hidden="true"></i></a></h3>

  165. <p>Determines the way (md) paths are treated by the tooling. The default value is <code>Full</code> for backwards compatibility.</p>

  166. <ul>

  167. <li><code>Full</code>: Assumes that all paths are full paths. All auto-generated index files will be placed in the root folder (this setting can lead to index clashes when reusing names in subfolders).</li>

  168. <li><code>Relative</code>: Assumes that all paths are relative paths. All auto-generated index files will be put in the right (sub)folder.</li>

  169. <li><code>RelativeAsFolder</code>: Behaves the same as <code>Relative</code>, but puts <em>every</em> source md in its own folder resulting in clean navigation urls (e.g. <code>/getting-started/introduction.htm</code> becomes <code>/getting-started/introduction/index.htm</code>)</li>

  170. </ul>

  171. <h3 id="urlformatting">UrlFormatting<a class="headerlink" href="#urlformatting" title="Permalink to this headline"><i class="fa fa-link" aria-hidden="true"></i></a></h3>

  172. <p>Determines how the urls are formatted. The default value is <code>None</code> which will only remove unsupported characters from the urls.</p>

  173. <ul>

  174. <li><code>None</code>: Does not touch the urls except from removing unsupported characters from the urls.</li>

  175. <li><code>Strip</code>: Replaces all non-text characters (e.g. spaces, dots, commas, etc) by an empty string (e.g. <code>/my-documentation/Some Introduction.md</code> results in <code>/mydocumentation/someintroduction.htm</code>)  
</li>

  176. <li><code>Dashes</code>: Replaces all non-text characters (e.g. spaces, dots, commas, etc) by a dash (<code>-</code>) (e.g. <code>/my-documentation/Some Introduction.md</code> results in <code>/my-documentation/some-introduction.htm</code>)  
</li>

  177. </ul>

  178. <h3 id="maxlevelintoc">MaxLevelInToC<a class="headerlink" href="#maxlevelintoc" title="Permalink to this headline"><i class="fa fa-link" aria-hidden="true"></i></a></h3>

  179. <p>Sets the level of headings to show in the Table of Contents (ToC). The default value is <code>2</code>. To show one additional level, one would use <code>3</code> for this value. </p>

  180. <div class="alert alert-info"><span class="alert-title"><i class="fa fa-info-circle"></i> Info</span><p>Note that level 1 headings (titles) are never shown in the ToC).</p>

  181. </div><h3 id="stripindexhtm">StripIndexHtm<a class="headerlink" href="#stripindexhtm" title="Permalink to this headline"><i class="fa fa-link" aria-hidden="true"></i></a></h3>

  182. <p>If set to <code>true</code>, the tool will strip <code>index.htm</code> from the end of urls. The default value is <code>false</code>. </p>

  183. <div class="alert alert-tip"><span class="alert-title"><i class="fa fa-info-circle"></i> Tip</span><p>Combined with <code>PathSpecification</code> set to <code>RelativeAsFolder</code>, this will result in a 'folder-based' browsing experience (e.g. <code>/getting-started/introduction/</code>)</p>

  184. </div><div class="alert alert-warning"><span class="alert-title"><i class="fa fa-warning"></i> Important!</span><p>Note that setting this value to <code>true</code> will remove the possibility to view the docs off-line                          
</p>

  185. </div><h3 id="footer">Footer<a class="headerlink" href="#footer" title="Permalink to this headline"><i class="fa fa-link" aria-hidden="true"></i></a></h3>

  186. <p>This is text and/or HTML which is placed in the footer of each page, using a <em>marker</em> (see below).</p>

  187. <h3 id="startingpagename">StartingPageName<a class="headerlink" href="#startingpagename" title="Permalink to this headline"><i class="fa fa-link" aria-hidden="true"></i></a></h3>

  188. <p>This is the name used for the home/starting page, i.e. the <code>__index</code> page at the root level. The default value is &quot;Home&quot;.</p>

  189. <h3 id="pages">Pages<a class="headerlink" href="#pages" title="Permalink to this headline"><i class="fa fa-link" aria-hidden="true"></i></a></h3>

  190. <p>Contains the pages to generate into the output, in the order and structure in which you want them to appear in the navigation. The name given is the value used in the navigation tree and has to be unique per level. The value specified with each name is the markdown file to load, parse and generate as .htm file in the output. The markdown file is relative to the path specified in <code>Source</code>. A file <code>foo.md</code> will be generated as <code>foo.htm</code> in the output. </p>

  191. <p>Paths are expected to use <code>\</code> characters, and as it's json, you have to escape them, so the path <code>.\foo</code> becomes <code>.\\foo</code>.</p>

  192. <p>Each level, starting with the root, has a special page defined, <code>__index</code>. This page is the page shown when the level header (in the example above this is e.g. <em>Sub Header 1</em>) is clicked in the navigation. If <code>__index</code> is specified in the root level, it's assigned to the navigation name <code>Home</code>. If there's no <code>__index</code> specified, there will still be a page generated but it will have default content (See below). The names of the elements are case sensitive.</p>

  193. <h2 id="levels-without-index-defined">Levels without __index defined<a class="headerlink" href="#levels-without-index-defined" title="Permalink to this headline"><i class="fa fa-link" aria-hidden="true"></i></a></h2>

  194. <p>If a level has no <code>__index</code> defined, <code>DocNet</code> will create a <code>__index</code> entry for the level and will specify as target <code>&lt;path to index of parent&gt;/nameoflevel.md</code>. If the page exists it will be loaded as the content for the index of the level, if it doesn't exist, the HTML will simply contain the topictitle and a list of all the sub topics in the level. This guarantees the tree can always be navigated in full.  
</p>

  195. <h2 id="use-of-wildcard-inclusions">Use of wildcard inclusions<a class="headerlink" href="#use-of-wildcard-inclusions" title="Permalink to this headline"><i class="fa fa-link" aria-hidden="true"></i></a></h2>

  196. <p>If a level has a string value ending with <code>**</code>, it will process all .md files in the folders and subfolders and generate htm files from them. It will use the following process:</p>

  197. <ol>

  198. <li>Search (recursively) for all markdown (<code>.md</code>) files inside the specified folder (e.g. <code>reference</code>)</li>

  199. <li>Generate index (htm) files for all folders</li>

  200. <li>The title of the markdown files will be retrieved from the actual markdown files (so the first non-empty line will be used as title)</li>

  201. </ol>

  202. <div class="alert alert-info"><span class="alert-title"><i class="fa fa-info-circle"></i> Info</span><p>The wildcard inclusion feature is extremely useful for referene or API documentation (mostly generated by a 3rd party tool)</p>

  203. </div>

  204.                     </div>

  205.                 </div>

  206.                 <footer>

  207.                     <hr />

  208.                     <div role="contentinfo">

  209. Made with DocNet. Get your copy at: <a href='https://github.com/FransBouma/DocNet' target='_blank'>https://github.com/FransBouma/DocNet</a>.

  210.                     </div>

  211.                 </footer>

  212.             </div>

  213.         </section>

  214.     </div>

  215.     <script src="js/jquery-2.1.1.min.js"></script>

  216.     <script src="js/modernizr-2.8.3.min.js"></script>

  217.     <script src="js/highlight.pack.js"></script>

  218.     <script src="js/theme.js"></script>

  219. 

  220. </body>

  221. </html>