The Flatworm Docs rendering engine is designed to be very simple, but provide enough formatting necessary for documenting JavaScript libraries.
A lot of its inspiration came from Read the Docs and the Sphinx project.
Each page is made up of fragments. A fragment is a directive, with an value and optional link, extensions and a body.
Many directives support markdown in their value and body.
A fragment's body continues until another fragment is encountered.
A definition has its TERM in normal text and the body is indented.
The title and body support markdown.
A property has its JavaScript SIGNATURE formatted.
The body supports markdown and the return portion of the signature support markdown links.
Extensions: @src
A note is placed in a blue bordered-box to draw attention to it.
The body supports markdown.
A warning is placed in an orange bordered-box to draw attention to it.
The body supports markdown.
Creates a Code block.
The body does not support markdown, and will be output exactly as is, with the exception of Code Evaluation.
If a line begins with a "_", it should be escaped with a "\".
Extensions: @lang
A toc injects a Table of Contents, loading each line of the body as a filename and recursively loads the toc if present, otherwise all the sections and subsections.
The body does not support markdown, as it is interpreted as a list of files and directories to process.
A null is used to terminated a directive. For example, after a definition, the bodies are indented, so a null can be used to reset the indentation.
The body supports markdown.
The markdown is simple and does not have the flexibility of other dialects, but allows for bold, italic, underlined, monospaced, superscript and strike text, supporting links and lists.
Lists are rendered as blocks of a body, so cannot be used within a title or within another list.
The code directive creates a monospace, contained block useful for displaying code samples.
For JavaScript files, the file is executed with some simple substitution.
A bare //! on a line is replaced with the result of the last statement. Building will fail if an error is thrown.
A bare //!error is replaced with the throw error. Building will fail if an error is not thrown.
Also any code included between the lines // <hide> and // </hide> will be omitted from the output, which can be used to setup variables.
The language can be specified using the @lang extension.
| Language | Notes | |
| javascript | Syntax highlights and evaluates the JavaScipt | |
| script | Same as javascript, but does not evaluate the results | |
| shell | Shell scripts or command-line | |
| text | Plain text with no syntax highlighting |
The table directive consumes the entire body up until the next directive. To terminate a table early to begin a text block, use a _null: directive.
Each line of the body should be Row Data or a Variable Declaration (or continuation of a Variable Declaration). Blank lines are ignored.
Each Row Data line must begin and end with a "|", with each gap representing the cell data, alignment with optional column and row spanning.
The alignment for a cell is determined by the whitespace surrounding the cell data.
| Alignment | Whitespace | |
| Left | 1 or fewer spaces before the content | |
| Right | 1 or fewer spaces after the content | |
| Center | 2 or more space both before and after the content | |
| Alignment Conditions (higher precedence listed first) | ||
| center | |
| left | |
| left | |
| right | |
| right | |
| Result of Alignment Example |
A column may end its content with any number of "<" which indicates how many additional columns to extend into.
If the cell content contains only a "^", then the row above is extended into this cell (into the same number of columns).
| (1x1) | (1x2) | (2x1) | ||
| (2x2) | (2x1) | |||
| (1x1) | ||||
| Result of Cell Spanning Example | ||||
The @style extension for a table can be used to control its appearance.
| Name | Width | Columns | |
| minimal | minimum size | best fit | |
| compact | 40% | evenly spaced | |
| wide | 67% | evenly spaced | |
| full | 100% | evenly spaced |
Often the layout of a table is easier to express and maintain without uneven or changing content within it. So the content can be defined separately within a table directive using variables. A varaible name must being with a letter and must only contain letters and numbers.
Variables are also useful when content is repeated throughout a table.
A variable is declared by starting a line with "$NAME:", which consumes all lines until the next variable declaration or until the next table row line.
A variable name must start with a letter and may consist of letters and numbers. (i.e. /[a-z][a-z0-9]*/i)
| Feature | Supported | |
| Dancing Monkey | This option is supported. | |
| Singing Turtle | This option is not supported. | |
| Newt Hair | This option is supported. | |
| This just represents an example of what is possible. Notice that variable content can span multiple lines. | ||
| Result of Variables Example | ||
Configuration is optional (but highly recommended) and may be either a simple JSON file (config.json) or a JS file (config.js) placed in the top of the source folder.
TODO: example JSON and example JS
Adds an inherits description to a directive. The markdown may contain links.
Set the language a code directive should be syntax-highlighted for. If "javascript", the code will be evaluated.
Sets the name in the breadcrumbs when not the current node.
Adds a note to a directive. The markdown may contain links. If the directive already has an @INHERIT extension, that will be used instead and the @NOTE will be ignored.
Calls the configuration getSourceUrl(key, VALUE) to get a URL which will be linked to by a link next to the directive.
This extended directive function requires an advanced config.js Configuration file since it requires a JavaScript function.
The Table Style to use for a table directive.