More Docs

Documon includes the ability to incorporate "more" information into the resulting website and menu using a simple directory and markdown file processor.

To incorporate "more" info:

  1. Create a folder and fill it with markdown files.
  2. (optional) Organize the files into sub folders.
  3. (optional) Use numbering prefix so things appear in the proper order.
  4. Point the ("more" option)[more.options] to the folder containing your markdown docs.

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.

- 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

The resulting menu will reflect the directory structure, and the numbering will be stripped out and not seen in the final menu:

- 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

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.

Organize with Numbering

If you want to keep the numbers, you'll have to double things up:

01.01 About.md
02.02 Install.md

Numbering requires a number followed by a "dot"

1.Foo.md
2.Bar.md

Numbers can be padded with zeros

01.Foo.md
02.Bar.md

001.Foo.md
002.Bar.md

Numbers must butt-up against the dot, for example:

01 .Foo.md

… will display in the resulting menu as:

01 .Foo

You can change the character that splits the numbering system from the label using the moreQuirkDelimiter option. For example if you set moreQuirkDelimiter = "#" you could use:

01#Foo.md
02#Bar.md

But be carefull when choosing a custom delimter because some operating systems choke on "reserved characters".

Meta Info

An optional Meta Info is available which allows you to do some tricky things such as:

The Meta Info is a standard JSON object located at the top of the markdown file:

{
    "url" : "https://www.gieson.com",
    "icon" : "fa-star"
}
__meta__

# My Page Title
yada yada

The line that reads "meta" acts as a flag (or boundary) that seperates the "head" from the normal markdown, if the "meta" flag exists, Documon extracts everything above from the page and processes the properties.

To create a menu item that links to some external URL, include a "url" property in the Meta Info json.

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.

Changing the Menu Icon

Use the "icon" property in the Meta Info -- set it's value to a CSS class definition.

Documon includes Font Awsome, so you can use any of their existing icon classes.

You can incorporate multiple classes:

{
    "icon" : "fa-star another"
}
__meta__

# My Page Title
yada yada

The DOCS-GO-HERE pointer

To position the doumentation generated from source code at a specific point int your "more" menu, create an empty file named DOCS-GO-HERE.md and place it into your "more" folder.

You can number the file:

04.DOCS-GO-HERE.md

And you can add additional text:

04.foo-DOCS-GO-HERE-bar.md

Documon just looks for the string "DOCS-GO-HERE" in the filename as a flag where to do the insertion.

If a DOCS-GO-HERE pointer is not used, the generated source code docs will appear at the bottom of the "more" menu.

Page ID's

Each "more" page is also provided with a unique ID, which is based on the path and filename of the markdown page.

The rules are as follows:

ID's are generated by stripping out numbering, and replacing non-alphanumeric characters with an underscore for both files and sub folders.

Then we use a dot.path convention (when a file is located within a sub folder).

And finally, the characters are all converted to lower case.

Example:

01.About.md
02.Sub folder 1
    01.Foo.md
    02.Bar's page.md
03.Install.md
04.Contact.md

In te example above the ID's for the files would be:

more.about
more.sub_folder_1.foo
more.sub_folder_1.bar_s_page
more.install
more.contact

Linking to "More" pages

The same rules for cross linking to other classes apply… use the page's ID.

Example:

[See the About Page](more.about)

General Notes

Including Images and Other Assets

Create a folder named "assets" within yoru "more" folder:

/path/to/more
/path/to/more/assets <--- here

The contents of this "assets" folder will get merged into the resulting website's asset folder.

NOTE: By default, Documon uses the folder named "assets" to store the websites css, js, images, etc.

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.

Generated by Documon