Skip to content
Tutorials Center
My learning

Topics

Lesson 29 of 39 ยท Markdown and Documentation

GitHub Flavored Markdown and Front Matter

Learn GitHub Flavored Markdown extensions - tables, task lists, strikethrough, autolinks, alerts, footnotes - and YAML front matter, with parsers you can run in Node.

CommonMark deliberately stays small. Real documents need tables, checklists and metadata, so most tools add extensions. The most widespread set is GitHub Flavored Markdown (GFM), a strict superset of CommonMark that GitHub documents and many renderers implement. Alongside it, static-site generators and documentation tools (Jekyll, Hugo, Astro, Docusaurus, and this site's lesson engine) read front matter: a block of YAML at the top of a Markdown file that carries metadata such as the title and publication date. This lesson covers both. The basics are in Markdown Syntax: The Complete Guide.

GFM tables

Tables use pipes and a header separator row. Colons in the separator set column alignment.

MARKDOWN
| Tool    | Type   | Stars |
| ------- | :----: | ----: |
| jq      | CLI    | 30000 |
| yq      | CLI    |  9000 |

:--- left-aligns, :---: centres and ---: right-aligns. The first row is the header, cells are trimmed, a literal pipe inside a cell is written \|, and the table ends at the first blank line. The columns do not have to line up in the source; padding is only for readability. Tables cannot contain block content such as lists or multiple paragraphs: for that, use HTML or restructure the data.

Task lists

A list item that starts with [ ] or [x] becomes a checkbox:

MARKDOWN
- [x] Write the draft
- [ ] Review
- [ ] Publish

On GitHub these are clickable in issues and pull requests, and a progress count appears beside them.

MARKDOWN
~~deleted text~~

Visit https://example.com or www.example.com directly.
  • ~~text~~ renders as <del>.
  • Extended autolinks turn bare URLs and www. addresses into links without angle brackets.
  • Disallowed raw HTML: GFM filters a few dangerous tags (such as <script>, <iframe>, <style>) even though other HTML passes through.
  • Footnotes ([^1] with [^1]: text) are supported by GitHub and many renderers, although they are not part of the original GFM spec.
  • Alerts use a block quote with a marker on the first line: > [!NOTE], > [!TIP], > [!WARNING]. This is a GitHub feature; other renderers show a plain quote.
  • Math ($x^2$), diagrams (a mermaid fenced block) and emoji shortcodes (:tada:) work on GitHub but depend on the renderer.

Always check what your final renderer supports. A document that uses extensions loses structure when shown in a plain CommonMark tool.

Node.js Parse a GFM table into objects

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Front matter

Front matter is a metadata block at the very start of a Markdown file, fenced by two --- lines (YAML, the most common) or +++ lines (TOML, used by Hugo). Tools read the block as data and treat the rest as the Markdown body.

MARKDOWN
---
title: "Getting Started"
date: 2025-03-14
tags: [intro, setup]
draft: false
---

# Getting Started

The body starts here.

Common uses are a page title, a description for search engines, an ordering number, tags, authors, a layout name, and flags such as draft. The front matter must be the first thing in the file (no blank line above it). A site generator parses it with a YAML library (see YAML Syntax Basics) and passes the values to templates. All the YAML gotchas apply: quote titles that contain a colon, and remember that an unquoted date may become a date object.

flowchart LR
  F["post.md"] --> S["split at the second ---"]
  S --> M["front matter (YAML)"]
  S --> B["body (Markdown)"]
  M --> D["data: title, tags, date"]
  B --> H["HTML"]
  D --> T["template"]
  H --> T
  T --> P["finished page"]

Front matter and body are processed separately, then combined by a template.

Node.js Split front matter from the body

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The parser removes a possible byte order mark first, requires the opening --- on the first line, and returns an empty data object when there is no front matter. A lesson on this site uses exactly this shape: title, description, order and section as data, then Markdown for the body.

Node.js Count task list progress

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Portability tips

  • Say in the project README which flavour you target (CommonMark, GFM, MDX, a custom engine).
  • Prefer tables only for real tabular data; use lists for everything else.
  • Keep front matter keys consistent across files, and validate them with a schema in CI (see Command-Line Data Tools).
  • MDX and similar systems let you embed components in Markdown. They are powerful but not interchangeable with plain Markdown.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is GitHub Flavored Markdown?

    GFM extends CommonMark; every CommonMark document is also valid GFM.
  2. 2. How do you right-align a table column?

    A colon on the right end of the separator cell right-aligns the column.
  3. 3. Where must front matter appear?

    Tools only recognise it as the first block of the file.
  4. 4. Which problem applies to front matter because it is YAML?

    All YAML pitfalls apply, so quote titles and identifiers.

Summary

  • GFM extends CommonMark with tables, task lists, strikethrough, autolinks and a few GitHub-only features.
  • Table separator colons set alignment; pipes in cells are escaped.
  • Front matter is a YAML (or TOML) block at the top of a file that becomes page metadata.
  • Extensions are renderer-dependent: know your target.
  • The parsers here are stand-ins that show the idea.

Next: Writing a Markdown-to-HTML Converter