Core syntax: | HeadingsParagraphsInline formattingHyperlinksImagesListsHorizontal rulesCode snippets |
Extended syntax: | Syntax highlightingTablesEmail addressesYouTube videosVimeo videos |
StackHub uses Fandoc for writing documentation. It is used for editing package readmes, vendor page content, and forum posts.
Fandoc is a lightweight and easy-to-use syntax that's similar to Markdown. Fandoc is intended to be almost plain text, similar to what you may write in a plain text email.
Core Features
StackHub presents all the core features available in the core Fantom fandoc library, listed below.
Headings
Headings are a title line followed by an "underline".
Heading 1 ######### Heading 2 ********* Heading 3 ========= Heading 4 ---------
Level 1 headings are generally reserved for page titles and are not encouraged for use within StackHub.
Paragraphs
Paragraphs are separated by a blank line:
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
Block quotes start the first line (or every line) of the paragraph with the >
character followed by a space:
> Lorem ipsum dolor sit amet, consectetur adipisicing elit, > sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. > Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
Inline formatting
- Inline code: 'FandocParser' - Strong: **foo bar** - Emphasis: *foo bar* - Strong+Emphasis: ** *foo bar* ** - Hyperlink: `https://stackhhub.org/` - Hyperlink: [StackHub Home Page]`https://stackhhub.org/`
- Inline code:
FandocParser
- Strong: foo bar
- Emphasis: foo bar
- Strong+Emphasis: foo bar
- Hyperlink: https://stackhhub.org/
- Hyperlink: StackHub Home Page
Hyperlinks
Use the backtick `
character to create hyperlinks:
`https://stackhhub.org/`
Use square brackets to mark up sections of text as links:
[StackHub Home Page]`https://stackhhub.org/`
Images
Images use the same syntax as a hyperlinks, but are prefixed with a bang:
![Alt text]`https://stackhub.org/images/logo.png`
You may even re-use images that have been packaged up in your pod using the Fantom fan
scheme:
![Logo]`fan://podName/res/logo.png`
Set an explicit size for an image as follows:
![Logo][128x64]`https://stackhub.org/images/logo.png`
You can make an image a link as follows with no spaces between the brackets:
[![Logo]`https://stackhub.org/images/logo.png`]`https://stackhub.org/`
Lists
Unordered lists use a dash followed by a space. Use indentation to indicate list hierarchy (two or more spaces):
- item 1 - item 2 - item 3 - sub 3a - sub 3b - item 4
Ordered lists use an identifier followed by a dot and space. The identifier can be a number, letter, or roman numeral (lower or upper case). Use indentation to indicate list hierarchy (two or more spaces):
I. Chapter I 1. Section 1 2. Section 2 a. Subsection a b. Subsection b II. Chapter II A. Section A B. Section B i. Subsection i ii.Subsection ii
Horizontal rules
Horizontal rules start with ---
, and must be preceded by a blank line:
Above the rule --- Below the rule
Code snippets
Anything indented two or more spaces is considered preformatted (like the <pre>
tag in HTML). Use when including code snippets or stacktraces.
You can also denote a block of text as preformatted by wrapping it with the special tokens pre>
and <pre
:
pre> - No markup - I mean it! <pre
Extended Features
StackHub also extends the core fandoc features with the following syntax extensions.
Syntax highlighting
Preformatted text may have syntax highlighting applied. Simply prefix the pre
text with:
syntax: XXXX
Where XXXX
is the name of the syntax to use. Example:
pre> syntax: fantom class Example { Void main() { echo("Hello Mum!") } } <pre
Common syntaxes include:
axon
csharp
css
fantom
html
java
javascript
xml
Tables
To render a HTML table, use preformatted text with table:
as the first line.
Table parsing is simple, but expressive. The first line to start with a -
character defines where the column boundaries are. All lines before are table headers, all lines after are table data.
pre> table: Full Name First Name Last Name ----------- ---------- --------- John Smith John Smith Fred Bloggs Fred Bloggs Judge Dredd Judge Dredd <pre
Becomes:
Full Name |
First Name |
Last Name |
---|---|---|
John Smith |
John |
Smith |
Fred Bloggs |
Fred |
Bloggs |
Judge Dredd |
Judge |
Dredd |
Note that any lines consisting entirely of -
or +
characters are ignored. This means the above table could also be written as:
pre> table: +-------------+-------+--------+ | | First | Last | | Full Name | Name | Name | -------------+-------+--------+ | John Smith | John | Smith | | Steve Eynon | Steve | Eynon | | Judge Dredd | Judge | Dredd | +-------------+-------+--------+ <pre
Email addresses
Nobody likes spam, but there are valid times when you really need to publish a contact email address. To help protect your address from being picked up by spambots, StackHub will guard against publishing it in plain text.
Give your email link a mailto:
scheme and StackHub will encode your email address and slowly reveal it to the user over time. There's no need for anchor text as it becomes the email address, so it may be simply written as:
`mailto:email.address@example.com`
YouTube videos
The image syntax may be reused to embed YouTube videos. YouTube videos are rendered full width and are responsive (they resize with the browser).
Simply use the YouTube share URL or the embed URL as the hyperlink:
![YouTube share URL]`https://youtu.be/2SURpUQzUsE` ![YouTube embed URL]`https://www.youtube.com/embed/2SURpUQzUsE`
For YouTube videos the image size attribute is repurposed as an aspect ratio:
![YouTube video][16x9]`https://youtu.be/2SURpUQzUsE`
Valid aspect ratios are [21by9]
, [16x9]
, [4by3]
, [1x1]
and defaults to 16x9 if not specified.
Vimeo videos
The image syntax may be reused to embed Vimeo videos. Vimeo videos are rendered full width and are responsive (they resize with the browser).
Simply use the Vimeo share URL or the embed URL as the hyperlink:
![Vimeo share URL]`https://vimeo.com/11712103` ![Vimeo embed URL]`https://player.vimeo.com/video/11712103`
For Vimeo videos the image size attribute is repurposed as an aspect ratio:
![Vimeo video][4x3]`https://vimeo.com/11712103`
Valid aspect ratios are [21by9]
, [16x9]
, [4by3]
, [1x1]
and defaults to 16x9 if not specified.