Featherdown Notes

This page is a companion to Featherdown, contains technical notes to self, plus some ideas for the future and a good list of references.

Technical Notes

A featherdown page is read in two main steps: determine layout and replace inline elements.

Layout

First, all layout elements are isolated.

Technically, each newline is assigned to a type; consecutive types are then compared using some precedence rules to establish the precise boundaries.

Inline elements

Within each layout element, all inline references are replaced by the result.

Technically, a sequence of regular expressions is compared against each "line" or "cell", until no more matches are found. Matches are immediately protected to avoid conflicts, while further matching occurs recursively for any "sub-cells" within each match. Finally, all protections are directly replaced with the respective results.

Preprocessing (optional)

Optionally, a pre-processing step occurs before determining layout, whenever in-page definitions are detected.

Technically, comments and blanks are seen as invisible layout elements, but one can imagine them vanish during preprocessing.

Design considerations

Interoperability with HTML

HTML mingles naturally, as the output of featherdown is just more HTML code. Lines that start with an HTML tag will only be parsed with respect to inline elements, but their layout won't be touched.

Interoperability with Javascript

Naturally, javascript code takes precedence over featherdown parsing (as featherdown itself is just another javascript module).

Repeated symbols

Tolerating repetition is a natural solution to match dead key behaviour in some keyboard layouts.

Plus it is always quicker to retype the same symbol a few times than type two or more different symbols.

Meaningful whitespace

This emerges naturally from the requirement that featherdown plaintext be readable as is, much like markdown.

Departures from markdown

Intentional

featherdown intentionally differs from markdown in three major items: tables, links and images:

• Images are always autodetected from the file extension, so no special syntax was needed.
• Tables resemble more Pandoc's simple table format. Because adding pipe separators is a hassle, and simple tabs are more, or at least equally visually clear. The tradeoff is nothing complex can be added inside tables.
• Links resemble more Wikipedia's markup, with the pipe as separator within single square brackets. It feels more intuitive and as a bonus uses 2 or 3 characters instead of 4.

Minor departures

• Italics using // instead of * (reserved for bold), also because the former symbol visually suggests slanting.
• Subscripts using ¨ instead of ~ (reserved for strikethrough)

Unintentional

• There is currently no nesting in blockquotes, as it seems to be rarely useful. This may change.

Future improvements

These are areas to improve on.

Reversibility

Featherdown should be reversible: the generated html output should enable reconstruction of the exact initial featherdown code, character by character. This will allow WYSIWYG live editing directly in the browser (coming soon).

Collisions

⚠ Grids and Setex level 6 are colliding at the moment

In addition, some operators could collide with each other in very specific situations:

• links vs mathematical vectors
• italics vs comments
• hashtags vs atx headings vs inline links
• footnote links vs normal links

Standalone script

A simple script, always up-to-date, selfcontained, to add featherdown parsing to any page, optionally subsetted to specific elements rather than the whole body, optionally also with only inline-elements.

Future Features

Better footnote autolinking

• Autolink footnote section without special syntax, base on the actual footnotes across the document
• long form autolinks for academic-like citations [#Featherdown 2022]
• fix the hash inconsistency [2] vs [#2].

Centered horizontal rule symbols

This would require injection of a particular style with the ::before CSS pseudo-element.

Note that the star symbol itself is not readily available in most keyboards, but emojis are available.

Friezes

Any line consisting solely of repeated (+10) pairs of characters could be detected as a frieze. Friezes would automatically be assigned a css class equal to the pair of repeated characters, allowing for further customisation.

Each pair is identified in alphabetical order, VA → AV.

In-table cell justification

Within cells, or at the table headers, using a combination of symbols (visually worse) would be a possible solution to the clash of tabs.

The order or quantity of these symbols wouldn't matter, only their presence.

There is another way, using the relative alignment of headers and a line separator just below them.

Finally, captions could possibly be coopted for the job.

Other Ideas

Buttons, perhaps using arrows to emphasise an action?  Text displayed ==› Action(...) , possibly enclosed in square brackets [ ] to use inline?

• Some way of generating fragment links for items besides headers
• citations, autoformatted

Announce section blocks somewhat resembling links [[[[[[[[[[[[[[[[[[[[link here]]]]]]]]]]]]]]]]]]]].

Autodetect Mac/Win and display a manual toggle, for keyboard shortcuts to alternate between e.g. CMD and CTRL.

Do not add task lists [ ] [x] and other rarely used features. Numbered lists,  1) 2) 3) too.

Nested sub and superscripts; nested items in blockquotes (probably not, its awful).

Collapsible sections with summary/details.

Wikipedia-style headings, using equals = like this: ======== title =========. Perhaps even instead of imposing particular symbols, try to autodetect depth level globally.

Direct html templates in external html files? Perhaps using a literal javascript object or a toml-like list afterwards?

Linking external libraries for math expressions, code syntax highlighting, etc…

Removed Ideas

Grids

Grids work like tables, except they must be preceded by a single dash line: ------------------------------------------------------------.

A number of consecutive lines below the dash line will be converted to grid rows; individual cells within each row are separated by tabs.

Column widths

Individual column widths may be specified within the dash line, using any CSS unit: -------- 25% ----------- 20em ----------- 100px --- 2fr ----.

• 25% ——20em ——————- 100px ————— 2fr ——

The exact position within the dash line can be adjusted to visually match the rows below. Spaces are ignored. Any missing widths default to 1fr, while excessive widths are discarded.

References

Syntax

These are some of the references that inspired the featherdown syntax or were otherwise good ancillary reading.

Live editing

Specific references for upcoming live editing functionality.