|featherdown-:=|
page.title is a light syntax [inspired by|featherdown-notes#references] Markdown — ==easy== to type, ==nice== to read and ==rich== in //shorthands//, yet compatible with //HTML// and javascript's //template literals// and amenable to ==live editing==.
images/featherdown.svg
((medium))
As [new ideas are incorporated|#future improvements] in page.title, this page and the companion [Cheatsheet|featherdown-cheatsheet] will be kept up-to-date.
Their sources, obviously written in **Featherdown**, can be read with [[Ctrl U]], or [:fountain-pen: **played with interactively**|featherdown-playground].
Shall page.title be useful to you too, fell free to @@@ contact site.author @@@ with any questions.
## Headings
Headings can be added in [#ATX] or [#Setex]-like fashion. If both formats are used in the same header, the latter one wins.
### ATX-like headings
Any line starting with an hash ´´#´´, followed by some text, is recognised as an header. The number of hashes determines depth:
DEPTH SYNTAX
heading 1 ´´# heading 1´´
heading 2 ´´## heading 2´´
heading 3 ´´### heading 3´´
... ...
Extra spaces around the hashes or after the heading text are ignored.
Setex-like headings
===================
Headings are also recognised whenever any line is underlined by another line containing the following long sequences of symbols, in decreasing order of visual density:
DEPTH UNDERLINE TYPE VISUAL DENSITY TEST
heading 1 hash ´´#################´´
heading 2 hash-equal ´´#=#=#=#=#=#=#=#=#´´
heading 3 equal ´´=================´´
heading 4 equal-dash ´´=-=-=-=-=-=-=-=-=´´
heading 5 dash ´´-----------------´´
heading 6 dash-space ´´- - - - - - - - -´´
The length of the underline must be at least 3 characters, excluding spaces. When the underline consists of different symbols, their precise order and relative amount does not matter.
## Paragraphs
Paragraphs are automatically placed around consecutive lines of text, as long as they do not match any other block element nor contain particular html tags.
### Left-aligned (default) or justified
Within a paragraph, text-alignment can be specified by the amount of tabs that precede it, the default (zero) resulting in left-aligned text.
Left-aligned: **0** tabs (default)
**1 -- 4** tabs will result in a completely justified block of text. Shall you have the habit of indenting the first line of a paragraph with a few tabs for visual clarity, you won't have trouble remembering this setting.
Left and justified paragraphs are automatically punctuated, unless they already end with a punctuation sign!
### Centered or right-aligned
Start a line with a substantial amount of tabs to produce a different alignment.
Centered
**5 -- 9** tabs
notice the blank lines
how they are
//mostly// kept
Right-aligned
**10 or more tabs**
Contrary to left-aligned and justified lines, no blank lines are needed to separate right- or left-aligned lines.This feels more natural when writing poetry, for example.
In addition, most blank lines are displayed, this affords a little extra creative freedom.
| A single [[tab]] is the same as [[space, space, space, space]].
## Polycolumns
Polycolumns present a block of text across an automatic number of (newspaper-like) columns, useful for ultra-long lists:
||||||||||||||||||||||||||||||||||
Heading, [#ATX-like]
Heading, [#Setex-like]
[#Paragraph]
[#Table]
[#Grid]
[#Polycolumn]
[#Quotation]
[#List]
Figure, block
Figure, inline
Link, [#fragment]
Link, [#inner]
Link, [#outer]
Code, fenced block
Code, inline
[#Verbatim]
[#Admonition]
[#Emoji]
[#Typographical replacements]
[#Caption]
[#Definition]
[#Shorthand]
[#Comment]
||||||||||||||||||||||||||||||||||
Fence any sequence of lines with 3 or more vertical bars: ´´|||´´ to create a polycolumn like the above.
Any [#blank lines] are ignored; in case they aid you organise the information visually.
## Tables
Two or more consecutive lines containing **tab-separated text** convert automatically into [#table] rows.
Adding one or more [#empty lines] between consecutive rows is possible.
Consecutive tabs, even if mixed with whitespace, count as one. Some rows may skip the last columns freely.
###Table header
To mark the first row as an **header row**, add an [#empty line] between the first and the second row. Alternatively, if the majority of the characters in the upper row are UPPERCASE, it will also be recognised as an header row.
###Empty cells
Empty cells are declared by writing a single dash ´´-´´
1 2 -
4 - 6
- 8 9
###Input labels
Input labels can be added anywhere in a table (or another searchable area) to automatically add or remove a tag from the search field.
The following code ´´#bold´´ creates a #bold label.
[[click]] it to search in the next available table the ´´bold´´ keyword.
###Column rewrites
Append ´´>>>Function´´ to any header to rewrite all cells in that column (by applying that ´´Function´´ individually to the resulting string)
| **Idea** Generalise the ´´>>>´´ operator to other situations, and maybe use a different symbol.
## Code
### Code blocks
Fenced code blocks may be added by sandwiching some lines between two fences: lines only containing three or more acutes ´´{{´´´}}´´.
´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´
{
this:is,
a:javascript,
object:"in a fenced code block"
}
´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´
### Code snippets
Inline code snippets are added by wrapping a bit of code in two acutes, like so ´´{{´´}} some code {{´´}}´´.
## Figures
Figures are recognised whenever the full path and the image extension ( .jpg, .png, .gif, .svg) are written, either as a [#block figure] or an [#inline image].
The default image folder is ´´images´´, so a simple image path like ´´feather.svg´´ resolves into ´´images/featherdown.svg´´ automatically.
| **Info**: Image paths containing spaces cannot be automatically recognised.
### Block figure
A single line containing a path to an image, with an optional caption and optional sizing in the lines below:
´´´´´´´´´´´´´´´´´´´´´´´´
images/featherdown.svg
((the Featherdown logo))
((small))
´´´´´´´´´´´´´´´´´´´´´´´´
This renders as:
images/featherdown.svg
((the Featherdown *logo*))
((small))
#### Sizing images
One extra line of [#captioned] text may be added below a block figure to specify the maximum horizontal image size, under the following formats:
FORMAT EXAMPLE EXAMPLE RESULT
Text ´´small´´ (also ´´medium´´) images/featherdown.svg ((small))
Pixels ´´20px´´ images/featherdown.svg ((20px))
Percent ´´10%´´ images/featherdown.svg ((10%))
Em units ´´5em´´ images/featherdown.svg ((5em))
Viewport units ´´5vw´´ or ´´5vh´´ images/featherdown.svg ((5vw)) images/featherdown.svg ((5vh))
((captioned text formats for sizing figures))
### Inline images
Images can also be referenced and sized inline (but without a caption). Alternatively, the [*I* shorthand|#shorthand] can be used anywhere, with captions.
## Style blocks
Style blocks follow a similar syntax as markdown.
SYMBOL STYLE SYNTAX EXAMPLE RESULT
´´**´´ bold (b) ´´**emphatic text**´´ **emphatic text**
´´//´´ italics (em) ´´//oblique text//´´ //oblique text//
´´==´´ highlight (mark) ´´==highlighted==´´ ==highlighted== text
´´__´´ underline (u) ´´__underlined text__´´ __underlined text__
´´~~´´ strikethrough (s) ´´~~redacted sentence~~´´ ~~redacted sentence~~ text
´´++´´ recent insertion (ins) ´´++newly added++´´ ++newly added++ text
´´||´´ spoiler ´´||hidden||´´ ||hidden|| but revealed on click
´´^´´ [#superscript] (sup) ´´basis^exponent´´ basis^exponent
´´^^´´ long superscript ´´some ^^long super.^^´´ some ^^long super.^^
´´¨´´ subscript (sub) ´´log¨2´´ log¨2
´´¨¨´´ long subscript ´´¨¨long subsc.¨¨´´ text with ¨¨a long subscript¨¨
´´{{´´}}´´ [#code] ´´{{´´}}code snippet{{´´}}´´ inline ´´code snippet´´
## Verbatim
Any expression can be written exactly as typed, without any symbol replacements (i.e. verbatim or escaped) by enclosing it in double curly braces ´´{{}}´´.
| *NB*: Empty curly braces display themselves rather than an empty space.
## Shorthands
### Keyboard and gesture shortcuts
Enclose any sequence of keyboard key combinations (or gestures) in double square brackets to produce nice visual keyboard-key icons, like ´´[[Ctrl C,Ctrl V]]´´: [[Ctrl C,Ctrl V]].
[A list of gestures exists|featherdown-gestures].
#### Simultaneous
Simultaneous keys or gestures are split by spaces, e.g. ´´[[Ctrl tap]]´´ to yield [[Ctrl tap]].
#### Sequential
Sequential keys or gestures are split by commas, e.g. ´´[[Alt, F]]´´ to yield [[Alt, F]].
### People
A known person may be referenced by prefixing ´´@´´ to an alphanumeric alias -- name or social network handle, without spaces (underscores allowed).
In addition, any number of aliases , split by commas, may be surrounded in two at-signs to produce an enumeration, like so ´´@@ Person 1, Person 2 @@´´.
### Contact button
Enclosing any sentence in triple at signs, e.g ´´@@@ ask about featherdown @@@´´ will yield a contact button:
@@@ ask about featherdown @@@
### Site and Page properties
Site and page properties can be accessed directly by subsetting: ´´page. ´´ or ´´site.´´ as deeply as needed. Some examples:
- ´´site.name´´: site.name
- ´´page.title´´: page.title
- ´´site.author´´: site.author
- ´´page.update´´: page.update
Certain properties are automatically formatted , by default, e.g ´´page.title´´ is always **bold** and [#dates] are recognised as usual.
### Functions
Any function can be called by name by enclosing its arguments in guillemets ´´« »´´, pipe-separated (´´|´´), like this: ´´MyFunction«arg1|arg2|...»´´. Arguments will be assumed strings, not wrapped in quotes.
### Buttons
A button can be created in the form ´´[some content]>>>FunctionCall()´´. For instance ´´[Press me!]>>>alert("Featherdown")´´ yields the following button: [Press me!]>>>alert("Featherdown").
### Dates
Dates are autodetected via the following patterns, and combinations thereof:
PATTERN NAME EXAMPLE RESULT
DD-MM-YYYY (day-month-year) ´´17-10-2022´´ 17-10-2022
reversed order ´´2022-10-17´´ 2022-10-17
slashed ´´17/10/2022´´ 17/10/2022
month named, short ´´17-Oct-2022´´ 17-Oct-2022
ordinals ´´17th October 2022´´ 17th October 2022
#### Date formats
To present a date differently, use the ´´D« »´´ [#function] with a format as the second argument.
FORMAT CODE RESULT
short date (default) ´´D«2022-10-17|Short»´´ D«2022-10-17|Short»
long date (superscripted) ´´D«2022-10-17|Super»´´ D«2022-10-17|Super»
long date (text only) ´´D«2022-10-17|Normal»´´ D«2022-10-17|Normal»
RSS ´´D«2022-10-17|RSS»´´ D«2022-10-17|RSS»
DD-MM-YYYY ´´D«2022-10-17|DD-MM-YYYY»´´ D«2022-10-17|DD-MM-YYYY»
YYYY-MM-DD ´´D«2022-10-17|YYYY-MM-DD»´´ D«2022-10-17|YYYY-MM-DD»
DD/MM/YYYY ´´D«2022-10-17|DD/MM/YYYY»´´ D«2022-10-17|DD/MM/YYYY»
YYYY/MM/DD ´´D«2022-10-17|YYYY/MM/DD»´´ D«2022-10-17|YYYY/MM/DD»
Finally, you can use the [#verbatim operator] to write a date precisely as you wish.
### Changestream
A changestream is a chronological log of changes, one per line:
- starting with a bold date (date of change)
- containing some text afterwards (change summary)
Thus the following snippet ´´**2023-09-06** Changestreams added to [featherdown]´´ will be formatted as:
**2023-09-06** Changestreams added to [featherdown]
## Links
Three types of links are recognised: **Outer links** point to external pages, **Page links** point to other pages in the current domain, and **Inner links** point to page sections.
Links [can be declared inline|#links] in a multitude of ways, using the ´´[]´´ operator and splitting arguments with ´´|´´.
cc/:=codes/core/
TYPE FULL LINK CODE TEXT SHOWN REFERENCE
fragment [#link] ´´[#link]´´ link {{#link}}
'' [inline link|#link] ´´[inline link|#link]´´ inline link ''
outer [example.com] ´´[example.com]´´ example.com https://example.com
'' [for example|example.com] ´´[for example|example.com]´´ for example ''
page [featherdown] ´´[featherdown]´´ Featherdown featherdown
'' [Featherdown Page|featherdown] ´´[Featherdown Page|featherdown]´´ Featherdown Page ''
local file [featherdown.js|cc/featherdown.js] ´´[featherdown.js|codes/core/featherdown.js]´´ featherdown.js cc/featherdown.js
page+inner [link table|featherdown#links] ´´[link table|featherdown#links]´´ link table {{featherdown#links}}
new tab (all types) [featherdown|] ´´[featherdown|]´´ Featherdown featherdown
### Fragment Links
As an additional shorthand to link to any heading in the page, enclose the first word from the desired heading in hashed brackets ´´[#like this]´´. Include more words at will - it ==just works==. So [#frag] (´´[#frag]´´), [#fragment links] (´´[#fragment links]´´) or [#fragment links GALORE] (´´[#fragment links GALORE]´´) all point to the same heading.
With great power comes great responsibility: do not give two headings the exact same names, or only the first one will be referenceable. Likewise, linking a single word requires precision, because ´´[#Inner]´´ becomes ambiguous when more than one heading starts with the word //Inner//.
###Outer Links
Outer links (to external pages) open in new tabs by default. Anything starting with ´´http´´ or that looks like a url will be usually recognised an outer link.
#### Auto outer links
If your url starts with ´´http(s)´´, and does not require a special title, you can even drop the brackets ´´[ ]´´, it will be recognised anyway. E.g. ´´https://pedros.works/featherdown-cheatsheet´´ displays as https://pedros.works/featherdown-cheatsheet .
To prevent auto-linking, enclose the url in [#verbatim] tags ´´{{}}´´.
###Inner Links
Inner links (to other pages or files in this domain) open in the same page tab by default. Anything not recognised as an [#outer link] will be seen as a inner link.
### New tab links
To force any link to open in a new tab, end with an additional separator ´´|]´´ .
## Footnotes
### Footnote Links
A footnote link is just a [#fragment link] to a special footnote section. The [#short] and [#long form].
#### Short form
To add a quick footnote, simply any integer inside a pair of square brackets [1] like so ´´[1]´´. Notice how it becomes automatically superscripted.
#### Long form
Longer footnotes can be created as a superscripted^[#second] [#fragment link], like so: ´´^[#second]´´. If not superscripted, it still works as a normal fragment link.
### Footnote Sections
All footnotes should be added to footnote sections, fenced by three or more circumflexes (pointing up) ´´^^^´´:
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1 This is the first footnote, referenced just like any fragment link
second This is the second footnote, referenced as a superscripted fragment link
3 This footnote references the first[1] and [#second] footnotes
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Footnote sections can be placed anywhere in the document, but typically appear at the end of a page or chapter.
If at the end of a document, the closing ´´^^^´´ fence may be omitted.
#### Implicit links
Currently, the first word/number of each line in a footnote is used to generate the target for the corresponding footnote link(s) in the document.
Automatic linking will be improved in the future :::TBA
Footnote sections are
## Quotations
>>> Any sequence of lines starting with ´´>´´ becomes a quotation.
((The featherdown))
This is written as follows. [#Captions], if added just below, specify authorship.
Obviously, trailing ´´>´´ are discarded, and spaces do not matter.
´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´
>>> Any sequence of lines starting with ´´>´´ becomes a quotation.
((The feather))
´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´´
## Captions
Captions are single lines wrapped in ´´((double parentheses))´´, which can be added to:
- [#tables] (classic caption)
- [#figures] (classic caption + sizing)
- [#quotes], denoting authorship
| **Idea** allow inline captions, after any item
## Lists
### Unnumbered lists
Unnumbered lists are recognised for any lines starting with an hyphen ´´-´´ possibly preceded by tabs to indicate sublist depth.
Tabs or 4 spaces are interchangeable.
´´´´´´´´´´´´´´´
-´´- first element´´
-second element
-3^rd element
-3.1 (nested)
-´´3.2´´
-and deeper, as
-there is ==no nesting limit==...
-going // back one level//
-or //several levels at once//
´´´´´´´´´´´´´´´
This generates the list:
-´´- first element´´
-second element
-3^rd element
-3.1 (nested)
-´´3.2´´
-and deeper, as
-there is ==no nesting limit==...
-going // back one level//
-or //several levels at once//
Depth levels should be sequential, otherwise the closest sequential depth level will be used.
## Typographical replacements
Some commonly used symbols can be typed faster with these replacements.
### Punctuation
NAME SYNTAX RESULT
em dash ´´--´´ —
ellipsis ´´...´´ …
interrobang ´´!?´´ ‽
irony ´´?!´´ ⸮
ditto ´´''´´ 〃
### Math
NAME SYNTAX RESULT
approx. equal ´´~=´´ ≈
plus or minus ´´+-´´ ±
minus or plus ´´-+´´ ∓
per mille ´´%%´´ ‰
basis point ´´%%%´´ ‱
multiplication ´´:*:´´ or ´´:x:´´ ×
### Miscellaneous
NAME SYNTAX RESULT
arrow left ´´<-´´ ←
arrow right ´´->´´ →
arrow both ´´<->´´ ↔︎
copyright ´´(c)´´ (c)
registered trademark ´´(r)´´ (r)
trademark ´´(tm)´´ (tm)
### Ordinals
Writing a number followed by a ´´th´´, ´´st´´, ´´nd´´ or ´´rd´´ will automatically superscript the latter, correcting some possible errors: ´´11st´´ becomes 11st and ´´21th´´ becomes 21th
### Emoji
#### Natural emoji
Naturally, emojis can be directly typed ⭐!
**Tip:** press [[meta dot]] to launch the emoji palette on windows.
#### Named emoji
Emoji are referenced with ´´:emoji-name:´´. The first emoji matching (containing) the name is picked. This allows for very short abbreviations, but also more specificity where available.
NAME SYNTAX EMOJI
grin ´´:grin:´´ :grin:
grin ´´:GRinniNG:´´ :GRinniNG:
grin ´´:grinning-face:´´ :grinning-face:
rabbit ´´:rabb:´´ :rabb:
rabbit ´´:rabbit:´´ :rabbit:
rabbit face ´´:rabbit-face:´´ :rabbit-face:
### Admonitions
Prepend a single pipe ´´|´´ to one or more lines to add an admonition:
The CSS class will be derived from the first word (or emoji), which won't be shown.
The four classic admonition styles are:
NAME RECOGNISED ALIASES EMOJI & COLOUR EXAMPLE CODE
*idea* idea, soon, futurely 💡 purple ´´| **Idea** This is a novel idea ´´
*info* tip, nb, note, information ℹ blue ´´| **info** This is an important note ´´
*pass* success, check, right, do, correct, yes, passed ✔ green ´´| :check: This is very correct´´
*warn* warning, beware, careful ⚠ yellow ´´| :warning: This is the last warning´´
*fail* danger, don't, wrong, no, nope, failed ❌ orange ´´| :wrong: This is totally wrong´´
| :Info: If the first word is not a recognised name, it will form the basis for a new, custom css class.
### Horizontal rules / line breaks
Horizontal rules mark a change in content, such as different chapters in a story or a thematic change.
A single line of 10+ underscores ´´________________´´ is recognised as one.
##Invisible elements
### Replacement rules
Any line containing the sequence ´´{{:}}=´´ will be detected as replacement rule. These help minimise repetitive typing.
For example, the replacement rule ´´hell{{o:}}=hi´´, replaces all ´´h{{e}}llo´´s into ´´hello´´s, across the page.
hello:=hi
//The replacement rule above is invisible, but works, even if the text appears beforehand.
### Comments
Any line starting with ´´//´´ will be ignored.
//This line is a comment and should be invisible.
### Blanks
Blank lines are those containing nothing or just tabs and spaces.
They are almost never rendered, except amidst [#centered and right-aligned] text.
___________________________________________________________________________________________________________________________________
That's a lot of info to take in. Luckily, there's a [cheatsheet|featherdown-cheatsheet] and a live [featherdown playground].
You may also wish to read the [technical notes|featherdown-notes], check the [references|featherdown-notes#references].
## Changes
**2022-10-29** [Featherdown]'s logo was upgraded -- it now describes itself, mirroring the syntax behaviour
**2022-10-27** [Featherdown] now enables warping to the line and column in the source code corresponding to the page's cursor position, even within nested elements, another step towards full live editing.
**2022-10-17** A new version of [*feather*|featherdown] with many new features was crafted.
**2023-09-29** The parser is now more robust against missing references (@Random8)
**2024-11-04** All data-related items are now asynchronous via placeholders (once the data arrives, it is replaced everywhere), solving a concurrency issue (@PinkHoodie, @JustImagineIt, @Random8)
**2024-11-16** Removed grids, since they were not much used, for simplicity and also to eliminate an existing conflict.