#
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 support and variables support 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

##
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 // 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.

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 |

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

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

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.

Name | Width | Columns |
minimal | minimum size | best fit |
compact | 40% | evenly spaced |
wide | 67% | evenly spaced |
full | 100% | 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 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`)

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

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

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.

The content of this site is licensed under the Creative Commons License. Last modified on June 12, 2020, 7:17pm.