documon

<!DOCTYPE html> <html> <head> <meta charset="utf-8"> <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1"> <title>More Docs</title> <meta name="description" content="more.more_docs.more_docs">  <link rel="stylesheet" href="assets/vendor/normalize.css">  <link rel="stylesheet" href="assets/vendor/prettify/codamike.css"> <script src="assets/vendor/prettify/prettify.js"></script>  <script> var pageCtx = { id : "more.more_docs.more_docs", name: "More Docs" } </script>  <link rel="stylesheet" href="assets/css/pages.css"> <script src="assets/js/documon/Storage.js"></script> <script src="assets/js/documon/Access.js"></script> <script src="assets/js/documon/Pages.js"></script> <script> (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) })(window,document,'script','https://www.google-analytics.com/analytics.js','ga'); ga('create', 'UA-106684927-1', 'auto'); ga('send', 'pageview'); </script> </head> <body> <div class="page"> <div class="more"><h1 id="more-docs">More Docs</h1> <p>Documon includes the ability to incorporate "more" information into the resulting website and menu using a simple directory and markdown file processor.</p> <p>To incorporate "more" info:</p> <ol> <li>Create a folder and fill it with markdown files.</li> <li>(optional) Organize the files into sub folders.</li> <li>(optional) Use numbering prefix so things appear in the proper order.</li> <li>Point the ("more" option)[more.options] to the folder containing your markdown docs.</li> </ol> <p>Below is an example directory structure, where we're using numbering to organize, and we've included sub-folders and the "DOCS-GO-HERE" pointer.</p> <pre><code>- 01.About This Thing.md - 02.Install This Thing.md - 03.Using This Thing.md - 04.DOCS-GO-HERE.md + 04.Some Sub Folder - 1.This is a long page title.md - 2.And this has spaces.md + 05.Another Sub folder - 1.Sally.md - 2.Bob.md - 05.Bar - assets - image.jpg</code></pre> <p>The resulting menu will reflect the directory structure, and the numbering will be stripped out and not seen in the final menu:</p> <pre><code>- About This Thing - Install This Thing - Using This Thing + packages <-------- the source file documentation + Some Sub Folder - This is a long page title - And this has spaces + Another Sub folder - Sally - Bob - Bar</code></pre> <blockquote> <p>NOTE: Yes, in our example there are 2 fours and 2 fives… This is fine because numbering is only used to order items, the numbers themselves are not important. You can even mix and match numbering with not numbering, just so long as the files are organized the order you prefer.</p> </blockquote> <h3 id="organize-with-numbering">Organize with Numbering</h3> <p>If you want to keep the numbers, you'll have to double things up:</p> <pre><code>01.01 About.md 02.02 Install.md</code></pre> <p>Numbering requires a number followed by a "dot"</p> <pre><code>1.Foo.md 2.Bar.md</code></pre> <p>Numbers can be padded with zeros</p> <pre><code>01.Foo.md 02.Bar.md 001.Foo.md 002.Bar.md</code></pre> <p>Numbers must butt-up against the dot, for example:</p> <pre><code>01 .Foo.md</code></pre> <p>… will display in the resulting menu as:</p> <pre><code>01 .Foo</code></pre> <p>You can change the character that splits the numbering system from the label using the <a href="more.options">moreQuirkDelimiter option</a>. For example if you set moreQuirkDelimiter = "#" you could use:</p> <pre><code>01#Foo.md 02#Bar.md</code></pre> <p>But be carefull when choosing a custom delimter because some operating systems choke on "reserved characters".</p> <h3 id="meta-info">Meta Info</h3> <p>An optional Meta Info is available which allows you to do some tricky things such as:</p> <ul> <li>Change the menu icon</li> <li>Link to an external URL from the menu.</li> </ul> <p>The Meta Info is a standard JSON object located at the top of the markdown file:</p> <pre><code>{ "url" : "https://www.gieson.com", "icon" : "fa-star" } __meta__ # My Page Title yada yada</code></pre> <p>The line that reads "<strong>meta</strong>" acts as a flag (or boundary) that seperates the "head" from the normal markdown, if the "<strong>meta</strong>" flag exists, Documon extracts everything above from the page and processes the properties.</p> <h3 id="external-menu-links">External Menu Links</h3> <p>To create a menu item that links to some external URL, include a "url" property in the Meta Info json.</p> <p>When a "url" property exists in the Meta Info, the menu button will load an external url -- something outside the documentaion website generated by Documon.</p> <h3 id="changing-the-menu-icon">Changing the Menu Icon</h3> <p>Use the "icon" property in the Meta Info -- set it's value to a CSS class definition.</p> <p>Documon includes <a href="https://fontawesome.io" target="_blank">Font Awsome</a>, so you can use any of their existing icon classes.</p> <p>You can incorporate multiple classes:</p> <pre><code>{ "icon" : "fa-star another" } __meta__ # My Page Title yada yada</code></pre> <h3 id="the-docs-go-here-pointer">The DOCS-GO-HERE pointer</h3> <p>To position the doumentation generated from source code at a specific point int your "more" menu, create an empty file named <strong>DOCS-GO-HERE.md</strong> and place it into your "more" folder.</p> <p>You can number the file:</p> <pre><code>04.DOCS-GO-HERE.md</code></pre> <p>And you can add additional text:</p> <pre><code>04.foo-DOCS-GO-HERE-bar.md</code></pre> <p>Documon just looks for the string "DOCS-GO-HERE" in the filename as a flag where to do the insertion.</p> <p>If a DOCS-GO-HERE pointer is not used, the generated source code docs will appear at the bottom of the "more" menu.</p> <h3 id="page-ids">Page ID's</h3> <p>Each <a href="more.more_docs">"more" page</a> is also provided with a unique ID, which is based on the path and filename of the markdown page.</p> <p>The rules are as follows:</p> <ul> <li>Numbering is stripped out</li> <li>non-alphanumeric characters are converted to underscores</li> </ul> <p>ID's are generated by stripping out numbering, and replacing non-alphanumeric characters with an underscore for both files and sub folders.</p> <p>Then we use a dot.path convention (when a file is located within a sub folder).</p> <p>And finally, the characters are all converted to lower case.</p> <p>Example:</p> <pre><code>01.About.md 02.Sub folder 1 01.Foo.md 02.Bar's page.md 03.Install.md 04.Contact.md</code></pre> <p>In te example above the ID's for the files would be:</p> <pre><code>more.about more.sub_folder_1.foo more.sub_folder_1.bar_s_page more.install more.contact</code></pre> <h3 id="linking-to-more-pages">Linking to "More" pages</h3> <p>The same rules for cross linking to other classes apply… use the page's ID. </p> <p>Example:</p> <pre><code>[See the About Page](more.about)</code></pre> <h3 id="general-notes">General Notes</h3> <ul> <li>Only markdown files with the "md" extension are read, so your "more" folder can contain other things as needed.</li> </ul> <h3 id="including-images-and-other-assets">Including Images and Other Assets</h3> <p>Create a folder named "assets" within yoru "more" folder:</p> <pre><code>/path/to/more /path/to/more/assets <--- here</code></pre> <p>The contents of this "assets" folder will get merged into the resulting website's asset folder.</p> <blockquote> <p>NOTE: By default, Documon uses the folder named "assets" to store the websites css, js, images, etc.</p> </blockquote> <blockquote> <p>NOTE: The name of the assets folder may differ from template to template, so check your template's "_config.js" "assetsFolder" setting before linking images or assets in your markdown.</p> </blockquote></div> </div> <div class="footer">Generated by <a href="http://www.documon.net" target="_blank">Documon</a></div> </body> </html>