_title: Flatworm Docs _section: Flatworm Docs The //Flatworm Docs// rendering script 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](link-rtd) and the [Sphinx](link-sphinx) project. _subsection: Fragments @ Flatworm Docs are made up of fragments. A fragment is either a lone body of [markdown](flatworm-markdown) text, or a [directive](flatworm-directive) for specialized formatting, which may itself have body. _heading: Directive Format _code: fragment.txt _heading: Flatworm Directives @ _definition: **_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. If an option is specified, it is avaialble as a name for intern linking. There should only be one ``_section:`` per page. _definition: **_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. If an option is specified, it is avaialble as a name for internal linking. _definition: **_heading:** //TITLE// A //heading// has its **TITLE** in an H3 font. If an option is specified, it is available as a name for internal linking. _definition: **_definition:** //TERM// A //definition// has its **TERM** bolded and the markdown body is indented. _definition: **_property:** //SIGNATURE// A //property// has its JavaScript **SIGNATURE** formatted and the markdown body is indented. _definition: **_note:** //TITLE// A //note// is placed in a blue bordered-box to draw attention to it. _definition: **_warning:** //TITLE// A //warning// is placed in an orange bordered-box to draw attention to it. _definition: **_code:** //FILENAME// A //code// reads the **FILENAME** and depending on the extension adjusts it. For JavaScript files, the file is executed, with ``\/\/!`` replaced with the result of the last statement and ``\/\/!error`` is replaced with the throw error. If the error state does not agree, rendering fails. _definition: **_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//. _definition: **_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. _heading: Examples _code: examples.txt _subsection: Markdown @ The markdown is simple and does not have the flexibility of other dialects, but allows for **bold**, //italic//, __underlined__, ``monospaced``, ^^super-scripted^^ text, supporting [links](flatworm-markdown) and lists. _code: markdown.txt _subsection: 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 _subsection: Extended Directive Functions @ _heading: @INHERIT\ Adds an inherits description to a directive. The //markdown// may contain links. This extended directive function is available for: - _section - _subsetion - _heading _heading: @SRC\ Calls the configuration ``getSourceUrl(text, 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`` [[flatworm-config]] file since it requires a JavaScript function. This extended directive function is available for: - _section - _subsetion - _heading - _property