Markdown

Markdown

Overview

Markdown is a document format created by John Gruber for writing for the web. The markdown syntax was designed to generate HTML from plain text (markdown) documents. Markdown (and its many variants) has become so ubiquitous that it is even used to generate formatted text beyond the web (e.g. in messaging platforms like Whatsapp, Slack, and Discord).

Learn Markdown

There are far too many excellent resources for learning markdown for us to attempt our own. Here are a few of our favorites:

• Markdown Guide by @ia.net¹
• CommonMark Tutorial by @commonmark.org
• Basic writing and formatting syntax by @github.com
• Working with advanced formatting by @github.com

Specification

HyperMark

The markdown engine in HyperTemplates is called HyperMark. HyperMark is based on the GitHub Flavored Markdown dialect, and compliant with the latest version of the CommonMark Specification.

HyperMark also adds some of our favorite features from the social media world, including @mentions, #hashtags, and :emojicodes:.

Frontmatter

HyperMark supports YAML-formatted frontmatter. Frontmatter is a block of structured data that lives at the top of every Markdown file, wrapped in an opening and closing --- demarcation.

1---
2created_at: "2025-05-20T15:00:00-07:00"
3title: About YAML Frontmatter
4description: An introduction to YAML frontmatter
5---
6
7Lorem ipsum, hipsters get some.

In this example lines 1-5 are Markdown frontmatter with three properties defined: created_at, title and description. These properties are made available to HyperTemplates as template data along with the body of the Markdown document as a field called content.

Learn more:

• YAML
• YAML frontmatter

@Mentions

HyperMark automatically converts @mentions to links (i.e. <a> elements). A @mention is a string that begins with the @ symbol, followed by any combination of alphanumeric, dot (.), underscore (_), dash (-), and forward slash (/) characters. A @mention must contain at least one dot (.) character.

All @mention <a> elements generated by HyperMark use the https:// URL scheme and have a boolean data-hyper-mention HTML attribute.

Example:

1Powered by @hypertemplates.net!

Output:

1<p>Powered by <a href='https://hypertemplates.net' data-hyper-mention>@hypertemplates.net</a>!</p>

#Hashtags

HyperMark automatically converts #hashtags to links (i.e. <a> elements). A #hashtag is a string that begins with the # symbol, followed by any combination of alphanumeric, underscore (_), and dash (-) characters. A #hashtag must contain one non-numeric character (e.g. #1 is treated as a numeric reference equivalent to "number one", not "hashtag one").

Please note the following details regarding automatically generated #hashtag links:

• All #hashtag <a> elements will use lowercase characters for the tag portion of the URL.
• All #hashtag <a> elements are generated with a configurable URL prefix and suffix.
  • The default prefix is /tags/ and the default suffix is /.
  • See the Website configuration reference, and the site.config.markdown property for more information.

Example:

1HyperTemplates is a pure #HTML templating system for the modern web.

Output:

1<p>HyperTemplates is a pure <a href='/tags/html/' data-hyper-mention>#HTML</a> templating system for the modern web.</p>

In this example, the default prefix (/tags/), lowercase tag name (html instead of HTML) and suffix (/) are used to create the link: /tags/html/.

:emojicodes:

HyperMark automatically converts :emojicodes: to their corresponding emoji characters. Over 1800 different emoji from the Unicode Emoji specification are supported. See below for a complete list.

Supported emoji codes