webifier.markdown registers content renderers for .md, .markdown, md=..., and markdown=... links. It also powers the default behavior for string content inside YAML sections, so you usually do not need kind: markdown; just write Markdown in a section's content.

config:
  webifier:
    extensions:
      site:
        uses: webifier.standard
      markdown:
        uses: webifier.markdown

Markdown rendering uses Python-Markdown with the bundled Webifier post-processing pass. In practice, that gives you:

• fenced code blocks with syntax highlighting.
• copy buttons on highlighted code blocks through webifier.standard.
• tables.
• footnotes.
• definition lists.
• attributes with attr_list.
• Markdown inside HTML blocks.
• inline and display math preserved for MathJax-style rendering.
• GitHub math image links converted back to readable math notation.
• local HTML/image/file link post-processing for img, audio, video, iframe, script, source, track, and embed.
• typed links such as md=..., notebook=..., pdf=..., and index=....

Markdown is the default text renderer for normal YAML section content, so plain strings, block scalars, tables, lists, code fences, and links can live directly inside page YAML.

Markdown pages can include a YAML page preface. The preface uses the same top-level syntax as a normal Webifier YAML page, and the rest of the file becomes the page body. A sibling page.yml file is also supported; the inline preface wins when the same key appears in both places.

---
title: Experiment Notes
nav: false
header:
  title: Experiment Notes
  description: Rendered from Markdown.
comments:
  kind: comments
  label: false
---

# Experiment Notes

This file becomes `experiment-notes.html`.

Common page preface keys:

• title: page title and header text.
• nav: override or disable the inherited navigation.
• footer: override or disable the inherited footer.
• config: page-local generation controls; this key is not rendered.

Any other page preface key is treated like a normal Webifier section and is rendered after the Markdown body. This is useful for authors, comments, related links, people cards, or other structured blocks that should follow the main content.

Renderer controls should be nested under config, grouped by the extension that owns them:

---
title: Course Notes
config:
  content_pages:
    toc: true
    cleanup: true
  markdown:
    toc: true

authors:
  kind: people
  content:
    - name: Ada Lovelace
      role: Author
---

Here, config.markdown and config.content_pages control the generated page, while authors renders after the Markdown content as a normal people section.

Markdown content pages get a generated collapsible table of contents by default when they have enough headings. The TOC is built from h1 through h4 headings after Markdown is rendered.

Disable it for one Markdown page:

---
title: Short Note
config:
  markdown:
    toc: false
---

# Short Note

Group related content-page controls under the same reserved config block:

---
title: Course Notes
config:
  markdown:
    toc: true
    cleanup: true
---

Site-wide defaults are normally set on the Markdown extension instance:

config:
  webifier:
    extensions:
      markdown:
        uses: webifier.markdown
        toc: true
        cleanup: true

Webifier exports those settings to config.markdown, and page preface config.markdown wins for one page. content_pages remains available as the shared lower-level content-page config.

A Markdown page preface is a small page YAML document. Webifier splits it into two groups:

• Reserved page keys configure the generated HTML page.
• Free-form keys become Webifier sections rendered after the Markdown body.

---
title: Paper Notes
header:
  title: Paper Notes
  description: Reading notes with links and comments.
nav: false
config:
  content_pages:
    toc: true
  markdown:
    toc: true

links:
  kind: links
  label: Related
  items:
    - text: Source paper
      link: https://example.com/paper.pdf
comments:
  kind: comments
  label: false
---

# Paper Notes

title, header, nav, and config do not render as content. The links and comments keys render as sections after the Markdown body.

This gives page renderer extensions a stable place to read behavior: config.<extension-key>. It also keeps visible page additions in the normal Webifier section syntax.

Webifier understands typed link prefixes inside Markdown. These links trigger rendering or copying while the current page is being processed.

Read the [project notes](md=notes/project.md).
Open the [notebook result](notebook=notebooks/result.ipynb).
Browse the [appendix](index=pages/appendix.yml).
View the [paper](pdf=assets/paper.pdf).

Link behavior:

• md=... and markdown=...: render a Markdown content page.
• notebook=...: render a notebook content page when webifier.notebook is enabled.
• pdf=...: render a PDF content page when webifier.pdf is enabled; otherwise copy the PDF as a file asset.
• index=...: render a YAML page.
• ordinary https://..., #anchor, and untyped links are left alone.

A Markdown Fragment

print("hello from a fenced block")

Inline math like \(x^2\) and display math:

Link a Markdown file with md=... to make Webifier render it as another reachable HTML page.

examples:
  kind: links
  label: Examples
  content:
    - text: Tiny Markdown page
      link: md=pages/user-guide/extensions/examples/tiny-markdown.md

• Tiny Markdown page

Enable the extension:

config:
  webifier:
    extensions:
      site:
        uses: webifier.standard
      markdown:
        uses: webifier.markdown

Use Markdown in YAML sections:

any_section_name:
  label: Optional visible label
  content: |
    Markdown goes here.

Link Markdown files:

[Rendered Markdown page](md=path/to/page.md)

Optional sibling page data:

path/to/
  page.md
  page.yml

For project-specific Markdown behavior, register a later content renderer for .md or md with override: true. Use that when you need custom parsing, preprocessing, or page wrapping.

config:
  webifier:
    extensions:
      markdown:
        uses: webifier.markdown
      lab_markdown:
        uses: my_lab.markdown
        override: true