Skip to content
All posts

The Markdown Publishing Toolkit: TOCs, Frontmatter, Callouts & Slides (2026)

A tutorial for authoring and publishing polished Markdown — generate a table of contents, manage frontmatter, add reading-time and callouts, create README badges, and present from Markdown.

The gap between "written" and "published" is full of small, fiddly tasks: a table of contents that stays in sync, frontmatter that matches your framework, a reading-time badge, callouts that render on your platform, README badges, and maybe a slide deck. This tutorial covers the author & publish tool group — the toolkit that turns a finished draft into a polished, publishable document.

The publishing toolkit

TaskTool
Table of contentsTOC generator
Frontmatter (YAML)Frontmatter editor
Reading-time badgeReading time estimator
Callouts / admonitionsCallout generator
README badgesGitHub badge generator
PresentationsMarkdown slides

Part 1: A table of contents that stays correct

Hand-written TOCs drift the moment you rename a heading. The TOC generator builds a GitHub-compatible table of contents with:

  • Depth limits (e.g., only H2–H3).
  • Ordered or unordered style.
  • HTML-marker injection so you can regenerate it in place when headings change.

It uses the same slug rules as the slug generator, so every TOC link resolves. For long READMEs and docs, a TOC is the single biggest navigation upgrade you can add.

Part 2: Frontmatter for any framework

Static site generators read YAML frontmatter at the top of each file — and each one wants slightly different fields. The frontmatter editor parses, edits, and serializes frontmatter with typed fields and one-click presets for:

  • Next.js, Astro, Hugo, Jekyll, Docusaurus, and generic MDX.
---
title: "My Post"
date: 2026-06-04
description: "A short summary for SEO and previews."
tags: ["markdown", "tutorial"]
draft: false
---

Consistent frontmatter is what makes bulk operations (sorting, filtering, RSS) work — see how the WordPress guide maps these fields during migration.

Part 3: Reading time

The reading time estimator produces a Medium-style "X min read" with realistic weighting:

  • Custom words-per-minute by audience (technical readers are slower).
  • Seconds per image and per code line — because nobody reads a 40-line code block at prose speed.

Add the result to your frontmatter or a badge. It's more accurate than a naive word-count-÷-200 estimate.

Part 4: Callouts and admonitions

Callouts (note/tip/warning boxes) render differently on every platform. The callout generator outputs the right syntax for your target:

> [!WARNING]
> This is the GitHub alert syntax.

It generates GitHub alerts, Obsidian callouts, Docusaurus admonitions, and MkDocs syntax from one source — so you don't memorize four dialects. See the platform-specific Obsidian and docs-as-code guides for where each renders.

Part 5: README badges

Badges communicate project health at a glance. The GitHub badge generator composes shields.io badges — npm version, GitHub stars, license, CI status, last commit, Node version — and outputs ready-to-paste Markdown:

![npm](https://img.shields.io/npm/v/your-package)
![license](https://img.shields.io/github/license/you/repo)

Pair with the GitHub README guide for a full README structure, and check the result with the README health score.

Part 6: Presenting from Markdown

Turn a document into slides with the Markdown slides tool: split on --- separators and step through with the keyboard. It's compatible with Slidev, Reveal.js, and Marp, so you can prototype a deck here and export to your framework of choice.

# Title slide

---

## Point one

- detail
- detail

---

## Thanks

A complete publish pass

Taking a finished draft to published:

  1. Frontmatter — set fields with the frontmatter editor.
  2. TOC — generate with the TOC generator.
  3. Reading time — add a badge from the estimator.
  4. Callouts — convert to your platform's syntax with the callout generator.
  5. Badges (for READMEs) — badge generator.
  6. Audit — final pass with the README health score.
  7. Publish — export via HTML/PDF or commit to your site.

Automating with the API

JobEndpoint
TOC/api/v1/generate/toc
Frontmatter/api/v1/extract/frontmatter
Reading time/api/v1/reading-time
Callout/api/v1/transform/callout

Common mistakes

1. Hand-maintained TOCs. They drift — generate with marker injection so they regenerate.

2. Inconsistent frontmatter. Breaks sorting, RSS, and filtering — use presets.

3. Naive reading time. Weight images and code, or you'll under-estimate technical posts.

4. One callout dialect everywhere. GitHub alerts don't render on MkDocs — generate per platform.

5. Publishing without a final score. Run the README health score as a last gate.

Quick reference

TaskTool
TOCTOC generator
FrontmatterFrontmatter editor
Reading timeReading time
CalloutsCallout generator
BadgesBadge generator
SlidesMarkdown slides

The publishing toolkit handles everything between "done writing" and "live." Generate the TOC, set clean frontmatter, add reading time and platform-correct callouts, and your documents ship looking professionally produced — every time.

Written by Markdown Viewer Team. Found this useful? Try the editor →

Keep reading

Hand-picked articles related to this one.