Skip to main content

​
Blog article markdown cheatsheet

This page lists the markdown and MDX syntax you can use in the blog article body editor (apps/portal/src/pages/superAdmin/blog/articles/editor/). Click the ? button in the editor toolbar to open this page in a new tab.

​
How it works

The editor is a Tiptap surface with a markdown mode. The article title is a separate field and becomes the page H1 on the marketing site. Body headings start at H2. The backend builds the table of contents automatically from headings H1–H4 found in the saved MDX body (apps/backend/src/utilities/blog/mdxParse.ts). You do not configure TOC in the CMS.

​
Supported syntax

​
Article title (H1)

Set the title above the editor. Do not add # Heading in the body for the main title.

​
Headings

​
Text emphasis

Underline is available from the bubble menu in rich-text mode; it serializes to HTML underline in markdown export.

​
Lists

​
Blockquote

​
Code blocks

Fenced blocks with optional language tag:

​
Horizontal rule

​
Tables (markdown mode only)

Paste or edit GFM pipe tables in Markdown mode. The public blog compiles them to HTML tables.
Stay in Markdown after pasting — rich text has no table toolbar and will not preserve pipe tables if you switch modes. The editor blocks switching to Rich text while the body contains a pipe table.

​
MDX components (in body)

These blocks can appear in saved MDX when inserted or pasted:

​
FAQ (optional, below editor)

Use Add FAQ under the body editor. Questions and answers are saved in frontmatter:
The marketing site renders this as an FAQ section on the article page.

​
Not supported in the editor

These appear in general markdown references (e.g. Markdown Cheatsheet) but are not available in the blog body editor today:
  • H1 (#) in body — use the title field
  • H4–H6 in the WYSIWYG toolbar (H4 may still appear in raw markdown paste; TOC includes levels 1–4 when present in saved MDX)
  • Task lists, footnotes, images in body (use cover / SEO image fields instead)
  • WYSIWYG table editing (use Markdown mode for pipe tables)
  • HTML blocks beyond what Tiptap markdown export allows

​
Extending this system

  1. Add or configure a Tiptap extension in apps/portal/src/pages/superAdmin/blog/articles/editor/ArticleBodyEditor.tsx.
  2. If the syntax is new to the pipeline, teach apps/backend/src/utilities/blog/mdxParse.ts to extract any derived data you need.
  3. Update the marketing MDX renderer if the block must display on the public site.
  4. Add a row to this cheatsheet page and register it in apps/documentation/docs.json under Frontend.
  5. Run make build module=portal and make test module=backend.

​
What not to do

❌ Never tell authors to manage the table of contents manually — it is generated on save.
❌ Never put FAQ content only in the body; use the FAQ section so frontmatter stays canonical.
❌ Never document syntax here without matching Tiptap / parseMdxContent behavior.

​
File conventions

​
What’s next?

📖 See also: Blog system architecture for scheduling, publishing, and discovery.
📖 See also: Frontend overview for how the portal fits together.
📖 See also: Marketing site for how published articles render on the public blog.