markdown.md

Markdown Features in Project Helix

Project Helix uses GitHub Flavored Markdown (GFM) with following extensions:

Sections

Use the section marker --- followed and preceeded by a blank line to create a section break. This is a change from GFM, where --- denotes a thematic break.

This is one section.

---

This is another section.

---

And this is a third section.

You can still create thematic breaks in Markdown by using any of the alternative syntaxes:

A line consisting of 0-3 spaces of indentation, followed by a sequence of three or more matching _ or * characters, each followed optionally by any number of spaces or tabs, forms a thematic break.

Section Metadata (or Midmatter)

GitHub allows (although not part of the GFM spec) adding metadata to a document by adding a YAML block, enclosed by pairs of --- to the beginning of the document. This is known as Markdown frontmatter.

---
key:value
---

This is my document.

Helix extends this notion by allowing to create YAML blocks at the beginning of a section.

This is one section.

---
key:value
---

This is another section. It has some meta data.

---

And this is a third section.

Because it looks like Markdown "frontmatter", but is allowed in the middle of the document, we call it "midmatter".

External Embeds

Embedding external content in a Markdown document is supported in Helix Markdown. We support a number of embedding syntaxes that were originally introduced for other software and allow a certain degree of interoperability:

Note: Helix Pipeline will only process embeds if the URL matches a known allow list. This is for reasons of security and to guard against accidental embeds.

IA Writer-Style Embeds

The IA Writer Markdown editing app for desktop and mobile operating systems introduced a system called content blocks and this embed style is inspired by the system.

An embed is:

• an allowed URL
• in a separate paragraph
• that's all.

https://www.youtube.com/watch?v=KOxbO0EI4MA

IA Writer-Style Embeds are the simplest and recommended way of creating embeds.

Gatsby-Style Embeds

This embed style is also supported by a number of Gatsby-plugins like gatsby-remark-embed-video. The implementation in Helix shares no code with these plugins.

An embed is:

• an inline code block
• in a separate paragraph
• containing a keyword, a colon :, and an allowed URL

`video: https://www.youtube.com/embed/2Xc9gXyf2G4`

In the example above, the keyword is video, but any keyword like embed, external, link, media is allowed.

Image-Style Embeds

The only notion Markdown has of external content embedded in the document are images. This embed syntax extends that idea by allowing embeds using the image syntax.

An embed is:

• an image ![]()
• with an allowed URL
• in a separate paragraph

![](https://www.youtube.com/watch?v=KOxbO0EI4MA)

Link + Image-Style Embeds

The downside of the three embed approaches above is that they do not work on GitHub and don't have a preview. This is solved by Link + Image-Style embeds, albeit at the cost of a more convoluted syntax.

An embed is:

• a link to an allowed URL
• in a separate paragraph
• with a preview image as the only child

[![Audi R8](http://img.youtube.com/vi/KOxbO0EI4MA/0.jpg)](https://www.youtube.com/watch?v=KOxbO0EI4MA "Audi R8")

Internal Embeds

Helix also supports internal embeds, similar to IA Writer's content blocks, with following changes:

• any of the external embed syntaxes are supported, not just IA-Writer-Style embeds
• allowed URLs must be relative and end with .md or .html

Data Embeds and Markdown Templates

Helix also supports the embedding of tabular or list data. This is useful for embedding data from external sources such as:

• Google Sheets (not yet supported)
• Microsoft Excel Online (not yet supported)
• Google Calendar (not yet supported)
• RSS Feeds (not yet supported)

Instead of just dumping the data as a Markdown table, Helix will fetch the data, and find placeholders in the current Markdown document (or section, if the document has sections) and fill the placeholders with the data from the data source.

If the data source has more than one entry, e.g. multiple rows in a spreadsheet, multiple events in a calendar, or multiple posts in an RSS feed, then the content of the document (or section) will be replicated for each entry.

Helix maintains a separate list of allowed URLs that indicate embeddable data sources, so any of the embed syntaxes describe above can be used. In the following examples, we will use the IA Writer-style syntax.

Example

Consider a fictional list of used cars, maintained in a spreadsheet:

Make	Model	Year	Image	Mileage (from)	Mileage (to)
Nissan	Sunny	1992	nissan.jpg	100000	150000
Renault	Scenic	2000	renault.jpg	75000	100000
Honda	FR-V	2005	honda.png	50000	150000

This list would be represented as a JSON document like this:

[
  {
    "make": "Nissan",
    "model": "Sunny",
    "year": 1992,
    "image": "nissan.jpg",
    "mileage": {
      "from": 100000,
      "to": 150000
    }
  },
  {
    "make": "Renault",
    "model": "Scenic",
    "year": 2000,
    "image": "renault.jpg",
    "mileage": {
      "from": 75000,
      "to": 100000
    }
  },
  {
    "make": "Honda",
    "model": "FR-V",
    "year": 2005,
    "image": "honda.png",
    "mileage": {
      "from": 50000,
      "to": 150000
    }
  }
]

The following examples use the above data.

Placeholders

To create a data embed, add an embeddable URL to the document and use placeholders like {{make}} or {{model}} in the document.

https://docs.google.com/spreadsheets/d/e/2PACX-1vQ78BeYUV4gFee4bSxjN8u86aV853LGYZlwv1jAUMZFnPn5TnIZteDJwjGr2GNu--zgnpTY1E_KHXcF/pubhtml

1. My car: [![{{make}} {{model}}]({{image}})](cars-{{year}}.md)

This will create following HTML (boilerplate omitted):

<ol>
  <li>My car:<a href="cars-1992.html"><img src="nissan.jpg" alt="Nissan Sunny"></a></li>
  <li>My car:<a href="cars-2000.html"><img src="renault.jpg" alt="Renault Scenic"></a></li>
  <li>My car:<a href="cars-2005.html"><img src="honda.png" alt="Honda FR-V"></a></li>
</ol>

Each of the placeholders have been replaced with entries from the table above.

Dot Notation

If you want to address nested properties (this will only be useful for some data sources), use a dot notation like {{mileage.from}}:

https://docs.google.com/spreadsheets/d/e/2PACX-1vQ78BeYUV4gFee4bSxjN8u86aV853LGYZlwv1jAUMZFnPn5TnIZteDJwjGr2GNu--zgnpTY1E_KHXcF/pubhtml

# My {{make}} {{model}}

![{{make}} {{model}}]({{image}})

Built in {{year}}. Driven from {{mileage.from}} km to {{mileage.to}} km.

to generate following HTML:

<h1 id="my-nissan-sunny">My Nissan Sunny</h1>
<p><img src="nissan.jpg" alt="Nissan Sunny"></p>
<p>Built in 1992. Driven from 100000 km to 150000 km.</p>

<h1 id="my-renault-scenic">My Renault Scenic</h1>
<p><img src="renault.jpg" alt="Renault Scenic"></p>
<p>Built in 2000. Driven from 75000 km to 100000 km.</p>

<h1 id="my-honda-fr-v">My Honda FR-V</h1>
<p><img src="honda.png" alt="Honda FR-V"></p>
<p>Built in 2005. Driven from 50000 km to 150000 km.</p>

Sections

If you have content that you don't want to see repeated for each data element, break it out in separate sections like this:

## My Cars

---

https://docs.google.com/spreadsheets/d/e/2PACX-1vQ78BeYUV4gFee4bSxjN8u86aV853LGYZlwv1jAUMZFnPn5TnIZteDJwjGr2GNu--zgnpTY1E_KHXcF/pubhtml

- [![{{make}} {{model}}]({{image}})](cars-{{year}}.md)

The first section, containing the "My Cars" headline won't be repeated in the generated HTML:

<div>
  <h2 id="my-cars">My Cars</h2>
</div>
<div>
  <ul>
    <li><a href="cars-1992.html"><img src="nissan.jpg" alt="Nissan Sunny"></a></li>
    <li><a href="cars-2000.html"><img src="renault.jpg" alt="Renault Scenic"></a></li>
    <li><a href="cars-2005.html"><img src="honda.png" alt="Honda FR-V"></a></li>
  </ul>
</div>

Notes for Developers

The new node types are documented in the MDAST schema documentation. The types mentioned in this document are:

• section
• embed
• dataEmbed