Documentation

Work-In-Progress

This is the start of the initial draft of NeoDoc's documentation. It's based off the existing parser and generally stable. While it's mostly stubs for additional documentation be be added later, it represents the full feature set and reference templates that come built into the library.

Section Types

NeoDocs are a collection of sections. Each section has a "type" that defines how it is parsed. These are those types:

• definitions - a definition list that translates into dl, dt, and dd tags in HTML output.

• checklist - a collection of items with a status associated with them.

• csv - a collection of CSV data.

• json - a JSON object.

• list - a list that uses bullets for each item (i.e. ul and li tags).

• markdown - for transforming markdown content

• numbered - a list that uses numbers for each item (i.e. ol and li tags).

• p - paragraph based content.

  This is the default type. Any section that isn't mapped to another type gets processed as paragraphs.

• raw - a raw block of text with no addition processing.

• yaml - for turning chunks of yaml into a data object.

Pre-Defined Sections

NeoDoc ships with a set of references templates to render HTML. They are used as fallbacks if an app doesn't provide a template for the given section.

Most of these are direct mappings the HTML elements. The default type for each section that's used to parse it is identified after it in square brackets.

(NOTE: All section will have a set of default attributes with specific default rendering. Some have additional built in attributes as well. Those details will be available in a future version of the docs)

The sections are:

• article [p]

  Wraps its content in an article tag instead of a section tag.

• aside [p]

• audio [p]

• block [p]

  wraps content in a div block instead of a section tag.

• blockquote [p]

  Attributes:

  • by
  • byURL
  • source
  • sourceURL

• canvas

• checklist [checklist]

• cli [raw]

  For command line input examples.

• code [raw]

  • First flag is the language passed to the syntax highlighter
  • fileName

• comment

  Apps are not require to remove the output of comment sections from the final output. The default templates do that, but there is no expectation that content from a comment section won't be included either hidden of visible in the generated output.

• content-warning [p]

  for content warnings.

  a -- label tag should be included.

• csv [csv]

  CSV data that's available on the page

  Include default -- headers: that is the number of header rows.

  Note that CSV to table conversion is app specific. Mating the specific table output is not required for compliant output.

• cw [p]

  alias for content-warning

• definitions [definitions]

• details

  Has default -- summary attr

• dialog [p]

  TODO: Figure out more about how this works if it should be included as default and what attributes need to be included by default.

• div [p]

  Wraps content in a div instead of a section tag.

• endnote [p]

• error

  for error message boxes.

• example

  For examples.

• figure [p]

  there is no default figcaption.

  Has a default `-- caption: `` attribute that is turned into a figcaption.

• footer [p]

• footnote [p]

• header [p]

• h1 [p]

• h2 [p]

• h3 [p]

• h4 [p]

• h5 [p]

• h6 [p]

• hr [p]

• html [raw]

  Apps are not required to render -- html sections. Doing so opens security considerations that apps must address independently.

• image [p]

  for images

  first flag is the image url/path/key

  apps are responsible for mapping the url/path/key to the image

  ideally, the image can be defined by the filename in a case insensitive way without requiring the file extension

  content of the section is used for the alt text.

  content should not have other tags in it.

  TBD of how to transform multi paragraph content to alt tags.

• info [p]

  For info boxes

• input [raw]

  Not sure about this one. The general idea is to be used as a corresponding thing for output so you can do:

  input - code - output

  That feels like it makes sense. just a little weird since input is also a category of native html tags.

  Pre formatted text in a section with a class="neo-input" attribute.

• list [li]

• loop [p]

  For GIFs and other looping assets.

• main [p]

• markdown [raw]

  for markdown content

• math [math]

• menu [list]

• nav [list]

• neo-head [raw]

  content for inserting raw text into the head of the document.

  This is primarily meant to be used when generating full HTML page.

  There is no expectation that apps will use this if the content is being included on another page instead of being a fully independent page.

• neo-head-link [raw]

  Attrs get put directly in link tags in the head when the output is a full document

  Ignored when the file content is used as an include on other pages.

  If there's content in the body of the section it's added in HTML comments in the output.

• neo-head-metatag [raw]

  for adding metatags to pages. Expectiation is this is for full pages. Not expecatation for being used when the full content of the file is being used as an include on other pages.

  If there's content in the body of the section it's added in HTML comments in the output.

• neo-json [raw]

  for JSON data that's made available on the page

• neo-metadata [p]

  page metadata.

  The -- template: attr will override the default processing template.

  The body of this section is used for the blur/description of the page. The expecation is that it's not displayed on the page itself but can be used by other content to display a short piece of text about what the page is about.

  The content should only be paragraph text with no nested sections or inline images.

  The -- image: attribute is for the open graph image.

  The -- square-image: attribute is for a square preview image

• neo-plugin [raw]

  For connecting to app specific plugins. There is no output from neo-plugin sections by default.

• neo-script [raw]

  NOTE: Apps are not required to include scripts in output. Doing so opens security considerations that each app must consider and address on their own.

  For adding scripts to the head of the document.

  Default to type="module". A section attribute can be used to override it.

  The default template doesn't render the script on the page.

  Templates can be used to render it inline in a code block. A default one is supplied.

  The reference output from the formatter includes classes for syntax highlighting but that's not required from other outputs. (i.e. the contents of the pre tag are up to the individual generator)

  There are non templates to render inline in the body of the document. That can be done by making a custom section (e.g. -- javascript) with it's own templates to perform the output.

• neo-style [raw]

  NOTE: Apps are not required to include style output.

  Works the same as script by for css.

• neo-template [raw]

  for storing templates for the page that the rendering engine can use if the app allows it. An id fields must exist for the engine to pick it up.

  The format is NeoJinja

• neo-vars [p]

  Not shows by default.

  Used to store attributes with strings that can be referenced by spans in the rest of the content.

  For example: -- link1: IMAGE_KEY can be accessed with >>some text|:link1>>

• neo-yaml [yaml]

  for YAML data that's made available on the page.

• noscript [p]

• notes [list]

• numbered [numbered]

  includes a -- start: attribute to set the starting number (TBD on how that works.

  includes a -- reversed flag

  includes a -- type: attr that expects "a", "A", "i", "I", or "1" to set the typ of identifier

• output [raw]

  Displays contents in a section with a `class="neo-output" attribute.

  NOTE: This does not use the <output> html element. That element has specific usage related for forms and aria implications.

• p [p]

• picture [p]

• pre [raw]

  pre formatted text

• preface [p]

• raw [raw]

• reference [p]

• section [p]

• spoiler [p]

  has a default -- label attr

  for setting up spoiler covered sections

• svg [raw]

• table [raw]

  Turns JSON into a table.

  TODO: Default basic JSON structure.

  Find a balance with given some structure (e.g. header rows, and thead/tbody/tfooter), but don't get to complicated (e.g. col/rowspan). Folks can make their own templates for this. This is just to provide something so there's a default.

  Folks can use the table and then define other templates for different outputs.

  Maybe provide an advanced template that allows for more functionality (e.g. col/rowspans)

• title [p]

  Title section for the page. The first block is treated as an h1 title by default that goes inside an hgroup tag. an optional -- subtitle: attribute can be added which will populate in the hgroup as well.

• tldr [p]

• todo [checklist]

• video [p]

• warning [p]

• youtube [p]

  TBD on this one. It probably makes sense even though it's hard coding in something that's specific to a company. Or, maybe it's just that it gets a default template without having a specific functionality requirement. But, still that's a hard coding. So, probably not. Probably better to just supply a batch of recommended templates with the expectation that they may change over time.

Excluded Tags

The following are HTML tags that represent sections that don't have default NeoDoc sections that correspond to them:

• hgroup - hgroups are the responsibility of output templates.

• embed - The -- html section type can be used if an embed is needed.

• form

• iframe - iframes can be added inside -- html sections if they are required.

• map - for image maps. Use -- html sections instead if thise is needed.

• object

• source - Used inside video tags, etc.. If that's necessary -- html sections can be used.

• textarea

• track

  TBD on what to do with the content section or if it should be displayed by default. Or if this should simply be an attribute (e.g of video) and not its own section type.

Under Consideration

These section types are under consideration but not currently included.

• path - for outputting a file path

Default Spans

As with the sections, NeoDoc ships with a reference set of templates for rendering spans of text. (i.e. those defined like <<strong|some text>>). They are mostly direct mappings to their HTML element counterparts.

They are:

• a

• abbr

• abbreviation

• b

  bring attention to element

• bdi

• bdo

• bold

• br

• cite

• code

• command

• data

• del

• delete

• dfn

• em

• emphasis

• footnote

• footref (for the return link to a footnote)

• html

• i

• id-link (app must be able to handle)

• image

• ins

• insert

• italics

• kbd

• keyboard

• link

• mark

• path

• q

• quote

• rp

• rt

• ruby

• s

• samp

• sample

• small

• span

• strike

• strong

• sub

• sup

• time

• u

• underline

• var

• wbr

Shorthands

NeoDoc provides this set of shorthands for text content that are processed natively in the parser. Each one includes a reference template for HTML output.

``code``

;;emphasis aka italics;;

^^footnote^^

@@footnote target@@

%%image%%

++keyboard++

>>link text|url>>

!!mark aka highlight!!

~~strike through~~

**strong aka bold**

__underline__

Custom Spans

<<custom|make your own thing here>>

Inline HTML

((raw html goes here))

Template Structure

The default templates are organized in a top down structure with the order:

/ Container / Category / Subcategory / Template 

Each item in the AST contains keys for all four to identify the target template to use for rendering.

The Containers

There are four top level containers.

• Section

• Wrapper

• Block

• Content

Each has specific categories and corresponding sub categories.

Details: TKTKTK