Fandoc Help

A Guide to the fandoc syntax

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/`

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`

Alt text

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`

Logo

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/`

Logo

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.