Documentation » Flatworm Docs

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, super^script 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 transpiled and executed in a VM, allowiung output (or exceptions) of blocks to be included in the fragment output.

The entire code fragment source is included in an async IIFE, whick means await is allowed, and several special comment directives are allowed.

A //_hide: will include any following code directly into the output, but will not include it in the generated output for the fragment.

A //_log: will include the value of any following expression in the output, prefixed with a // . Renderers will mark output in different style if possible.

A //_result: will begin a block, assigning the contents to _. The block can be ended with a //_log: or //_null:, if no value is given to log, then _ is assumed. If an error occurs, generation fails.

A //_throws: will begin a block, which is expected to throw assigning the error to _. The block can be ended with a //_log: or //_null:, if no value is given to log, then _ is assumed. If an error do not occur, generation fails.

Code Evaluation Example

_code: Result of Code Example @lang<javascript> //_hide: const url = require("url"); //_result: url.parse("https://www.ricmoo.com/").protocol //_log: //_throws: url.parse(45) //_log: // You want to assign (doesn't emit eval) AND display the value const foo = 4 + 5; //_log: foo

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.

Language	Notes
javascript	Syntax highlights and evaluates the JavaScript
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

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

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. Generated on April 6, 2023, 1:54am.