Flatworm Docs

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.

Fragments

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.

Directive Format

_DIRECTIVE: VALUE @<LINK> @EXTENSION<PARAMETER> BODY MORE BODY DIRECTIVE: The directive name VALUE: Optional; the value to pass to the directive LINK: Optional; a name for internal linking EXTENSION: Optional; extended directive functionality PARAMETER: Optional; value to pass to extended directive functions BODY: Optional; the directive body (certain directives only)

Flatworm Directives

_section: TITLE

A section has its TITLE in an H1 font. Sections are linked to in Table of Contents and have a dividing line drawn above them.

The body supports markdown.

There should only be one _section: per page.

Extensions: @inherit, @src, @nav, @note

_subsection: TITLE

A subsection has its TITLE in an H2 font. Subsections are linked to in Table of Contents and have a dividing line drawn above them.

The title and body support markdown.

Extensions: @inherit, @src, @note

_heading: TITLE

A heading has its TITLE in an H3 font.

The title and body support markdown.

Extensions: @inherit, @src, @note

_definition: TERM

A definition has its TERM in normal text and the body is indented.

The title and body support markdown.

_property: SIGNATURE

A property has its JavaScript SIGNATURE formatted.

The body supports markdown and the return portion of the signature support markdown links.

Extensions: @src

_note: BANNER

A note is placed in a blue bordered-box to draw attention to it.

The body supports markdown.

_warning: BANNER

A warning is placed in an orange bordered-box to draw attention to it.

The body supports markdown.

_code: CAPTION

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

_table: FOOTER

Creates a Table structured according to the body.

Each cell contents supports markdown and variables supports markdown.

Extensions: @style

_toc:

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.

_null:

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.

Example
_section: Hello World @<link-main> Body for section... _subsection: Some Example @<link-secondary> Body for subsection... _heading: Large Bold Text @<link-here> Body for heading... _definition: Flatworm A phylum of relatively **simple** bilaterian, unsegmented, soft-bodied invertebrates. _property: String.fromCharCode(code) => string Returns a string created from //code//, a sequence of UTF-16 code units. _code: heading // Some code goes here while(1); _table: Table Footer | **Name** | **Color** | | Apple | Red | | Banana | Yellow | | Grape | Purple | _toc: some-file some-directory _note: Title This is placed in a blue box. _warning: Title This is placed in an orange box. _null: This breaks out of a directive. For example, to end a ``_note:`` or ``_code:``.

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.

**bold text** //italic text// __underlined text__ ``monospace code`` ^^superscript text^^ ~~strikeout text~~ - This is a list - With bullet points - With a total of three items This is a [Link to Ethereum](https://ethereum.org) and this is an [Internal Link](some-link). This is a self-titled link [[https://ethereumorg]] and this [[some-link]] will use the title from its directives value.

Code

The code directive creates a monospace, contained block useful for displaying code samples.

JavaScript Evaluation

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.

Code Evaluation Example
_code: Result of Code Example @lang<javascript> // <hide> const url = require("url"); // </hide> url.parse("https://www.ricmoo.com/").protocol //! url.parse(45) //! error // You want to assign (doesn't emit eval) AND display the value const foo = 4 + 5; // <hide> foo // </hide> //!
Result of Code Example
url.parse("https://www.ricmoo.com/").protocol // 'https:' url.parse(45) // Error: The "url" argument must be of type string. Received type number (45) // You want to assign (doesn't emit eval) AND display the value const foo = 4 + 5; // 9

Languages

The language can be specified using the @lang extension.

LanguageNotes 
javascriptSyntax highlights and evaluates the JavaScript 
scriptSame as javascript, but does not evaluate the results 
shellShell scripts or command-line 
textPlain text with no syntax highlighting 

Tables

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.

Row Data

Each Row Data line must begin and end with a "|", with each gap representing the cell data, alignment with optional column and row spanning.

Alignment

The alignment for a cell is determined by the whitespace surrounding the cell data.

AlignmentWhitespace 
Left1 or fewer spaces before the content 
Right1 or fewer spaces after the content 
Center2 or more space both before and after the content 
Alignment Conditions (higher precedence listed first) 
Alignment Example
_table: Result of Alignment Example @style<compact> | center | | left | |left | | right | | right|
center 
left 
left 
right 
right 
Result of Alignment Example 

Row and Column Spanning

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).

Cell Spanning Example
_table: Result of Cell Spanning Example @style<compact> | (1x1) | (1x2) <| (2x1) | | (2x2) <| (2x1) | ^ | | ^ | ^ | (1x1) |
(1x1)(1x2)(2x1) 
(2x2)(2x1) 
(1x1) 
Result of Cell Spanning Example 

Styles

The @style extension for a table can be used to control its appearance.

NameWidthColumns 
minimalminimum sizebest fit 
compact40%evenly spaced 
wide67%evenly spaced 
full100%evenly spaced 

Variables

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 variable name must begin 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)

Variables Example
_table: Result of Variables Example $Yes: This option is supported. $No: This option is **not** supported $bottom: This just represents an example of what is possible. Notice that variable content can span multiple lines. | **Feature** | **Supported** | | Dancing Monkey | $Yes | | Singing Turtle | $No | | Newt Hair | $Yes | | $bottom <|
FeatureSupported 
Dancing MonkeyThis option is supported. 
Singing TurtleThis option is not supported. 
Newt HairThis 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

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

Extensions

@inherit< markdown >

Adds an inherits description to a directive. The markdown may contain links.

@lang< text >

Set the language a code directive should be syntax-highlighted for. If "javascript", the code will be evaluated.

@nav< text >

Sets the name in the breadcrumbs when not the current node.

@note< markdown >

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.

@src< key >

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.

@style< text >

The Table Style to use for a table directive.