AsciiDocsy Frontend Overview
The AsciiDocsy theme is not exactly groundbreaking in its layout. This is by design.
There may be some cases when a unique format or layout is called for in documentation, but they are few and far between. Users want predictability. They want “intuitive” layouts where everything is where they expect.
In that spirit, AsciiDocsy’s layout is conventional. There are four navigation areas surrounding the content of each page.
Figure 1. AsciiDocsy’s navigation model
Let’s examine these navigation areas more closely.
Site Menus and Navigation
Typically used for sitewide pages or key external links, the #topnav menu can accommodate a layer of nesting, if needed.
Subject Navigation (Left)
You are welcome to use the subject menu (#subject-menu) for anything you wish, of course, just as you are welcome to hide it.
It is set up as generically as possible, with repurposing in mind.
That said, #leftbar-situated nav menu is mainly intended to reference either a simple lists of topics within your subject or complex, nested combinations of links to topics and artifacts for a subject or a set of subjects.
| The subject menu does not at this time have a way of inferring a menu from the filesystem or even from page metadata (frontmatter). While this functionality is possible, I have found it clunkier than centralized “manifest” data files that coordinate page and topic metadata. |
Page Navigation (Right)
The right sidebar contains navigation and other features relevant to the current page or topic.
Page Links
Every page with a page or topic layout has a number of optional links to alter the page appearance or submit edits.
Data Edit Link
Since some pages in an AsciiDocsy site can be sourced as data and pressed into rich-text form using Liquid templates, linking to the source data file can be helpful.
Figure 2. AsciiDocsy lets you link to the AsciiDoc source and the underlying YAML file.
See this feature in action in the Configuration API Reference.
Topic TOC
The topic table-of-contents is generated by Bootstrap’s scrollspy component. The client (browser) renders headers of designated levels into TOC items with anchor links.
| This feature does not use AsciiDoc’s built-in TOC generator, which can still be embedded in the page itself. |
The TOC remains in a static position as you scroll the page, tracking your position by highlighting the appropriate item in the TOC.
Company Navigation (Bottom)
The company nav consists of up to five columns of links. Link hrefs can draw data from additional sources, as well.