Neopolitan

Details (Draft)

Here's the specifics on how to format a Neopolitan note.

(A full technical spec and test suite is pending. I'm also making examples that will likely be easier to process via the show don't tell principal.)

Notes

• Neopolitan notes are made of blocks
• There are two types of blocks: Basic and Wrapper (details below)
• Blocks can have attributes and flags (details below)
• Blocks can contain content made up of spans
• Blocks without content are permitted
• Content before the first block is not permitted
• Spans are either: plain-text, shorthands, or tags (details below)
• Shorthand and Tag spans can have attributes and flags (details below)

Basic Blocks

• Basic blocks start with a line containing two hyphenes and a name separated by a one or more spaces
• Name can't contains spaces
• Other than the first block, at least one empty line must precede all blocks
• At least one empty line must be placed between the start of a block (including attributes and flags) and any content
• The contents of a basic block continue until reaching either a new block or the end of the note
• Each block belongs to a category (see below)
• A block's category determines how its content is treated
• Block categories can be defined by an app or via a type attribute on the block itself
• A set of requirements for blocks that belong to specific categories is forth coming. Apps are required to use the categories in order to be considered a valid Neopolitan app
• A set of recommended categories for specific blocks is forthcoming. Apps should follow these recommendations if possible to assist in portability, but there's no requirement to do so.
• Apps are required to honor type attributes if a block has one

Wrapper Blocks

• Wrapper blocks contain content between starting and ending lines
• Starting lines consist of two hyphens, one or more spaces, a name, and a / character
  
  

  -- book-review/
  

• Ending lines consist of two hyphens, one or more spaces, a / character, and the same name that was used on the starting line
  
  

  -- /book-review
  

• Basic blocks can be included inside wrapper blocks:
  
  

  -- book-review/
  
  Some basic notes
  
    -- supplemental-info
  
    More details
  
  -- /book-review

• Wrapper blocks can contain other wrapper blocks.
  
  

  -- book-review/
  
  Some basic notes
  
    -- supplemental-info/
  
    More details
  
    -- /supplemental-info
  
  More content
  
  -- /book-review

• Blocks contained inside a wrapper block can be tabbed over or kept flush starting at the first column of the note
• There's no practical limit to the number of basic or wrapper blocks can be used as siblings inside a wrapper block
• There's no practical limit to the depth of the nesting
• Content after the ending line is treated like an basic category block

Block Categories

• The core block categories are: Basic, Checklist, Checklist Item, CSV, JSON, List, List Item, Numbered List, Numbered List Item, Raw, and Text Content.
• Table is a reserved category type without an initial implementation. (I don't foresee a generalized table being implemented in the parse but want to make sure the name is free in case it does)
• Each category parses the contents of a block in a specific way
• If a block doesn't have a type attribute, and it doesn't match one of the predefined categories, and the app doesn't define it implicitly it is processed as a Basic block
• Apps are required to accommodate the core categories
• Apps can design and implement their own categories to parse content in ways the core categories don't
• Details about the handling of each category will be provided in further documentation

Block Attributes and Flags

• type - for defining what category a block should be parsed with
• plugin - passes the block off to another process for parsing

• wiki - for defining terms on a page or block that apps should use for wiki links

Plain-Text Spans

Shorthand Spans

Shorthands offer a way to quickly enhance content in Neopolitan files. They are:

~~ = strikethrough 

`` = code

^^ = footnote

** = strong

__ = emphasis

@@ = wikilink

:: = image

(( and )) = html

[[ and ]] = link

{{ and }} = class wrapper

Tag Spans

Span Attributes And Flags