Choosing a Markdown Flavor for Reliable Static Site Generation

Problem: Inconsistent Rendering Across Tools

You write a Markdown file that looks fine in VS Code, but when the same file is processed by Hugo or Jekyll, tables disappear or task‑list checkboxes are missing. This occurs because the term “Markdown” covers several, mutually incompatible specifications.

Thesis: Pick a Baseline and Explicitly Enable Needed Extensions

Choose a baseline specification—CommonMark v0.30—because it is the only versioned, interoperable standard. Then add only the extensions your pipeline actually requires, such as tables or task lists, and verify that the parser you use supports them.

Worked Example: Configuring markdown‑it for GFM‑like Features

In a Node‑based build you can use the popular markdown-it parser and add plugins for the GFM features you need.

// Install: npm i markdown-it markdown-it-task-lists markdown-it-table
const MarkdownIt = require('markdown-it');
const md = MarkdownIt()
  .use(require('markdown-it-task-lists'))
  .use(require('markdown-it-table'));

const source = `
| Task | Done |
|------|------|
| Write draft | [x] |
| Review      | [ ] |
`;

console.log(md.render(source));

Running this script prints HTML that includes <table> and <input type="checkbox"> elements. If you omit the markdown-it-table plugin, the same source yields raw pipe characters, confirming the missing extension.

Trade‑off and Limitation

Adding extensions improves expressiveness but re‑introduces parser fragmentation: a document that relies on GFM‑specific tables will break in a tool that only implements CommonMark. The safest approach is to limit extensions to those universally supported by your target SSGs, or to provide a fallback (e.g., raw HTML) for critical content.

Actionable Closing

1. Run the CommonMark test suite against your chosen parser to confirm baseline compliance.
2. For each GFM feature you plan to use, render a small snippet and check for the expected HTML tag (e.g., <table> for tables).
3. Document the exact parser version and plugin list in your repository’s README so future contributors can reproduce the rendering.