Markdown authoring

uid: guides.markdown description: Every Markdown construct pudu-lang-docgen supports, each shown as source and as rendered output.

Articles are written in CommonMark with a set of extensions for technical documentation. Each section below shows the source first and the rendered result after it.

[!NOTE] Raw HTML is allowed but reduced to a safe set of elements and attributes. Scripts, styles, event handlers, and unknown elements are shown as text instead of being executed.

Front matter

An article can start with a YAML block between --- lines. Its keys become page metadata and override global and file metadata.

title: Markdown authoring
uid: guides.markdown
description: Shown in search results and link previews.
keywords: [markdown, authoring]
_disableAffix: true

Every template key described in Templates and theming can also be set here.

Headings

ATX (#) and setext (underlined) headings are supported. Each heading gets a fragment derived from its text; write {#id} at the end to choose it. Level-two and level-three headings appear in the In this article outline.

### Heading with a custom fragment {#custom-fragment}

Heading with a custom fragment {#custom-fragment}

This heading links as #custom-fragment.

Inline formatting

**bold**, *italic*, ~~strikethrough~~, `code`, H~2~O, x^2^, ++inserted++, ==marked==

bold, italic, ~~strikethrough~~, code, H~2~O, x^2^, ++inserted++, ==marked==

A backslash at the end of a line, or two trailing spaces, forces a line break.\ This line follows a hard break.

Lists

- Bullet item
  - Nested item
1. Ordered item
2. Second item
- [x] Completed task
- [ ] Open task

• Bullet item
• Nested item

1. Ordered item
2. Second item

• [x] Completed task
• [ ] Open task

Links and images

Relative links name the Markdown source; the build rewrites them to the published page and reports targets that do not exist. Fragments are checked against the target page's headings.

[Configuration reference](configuration.md#build-settings)
<https://www.pudu-lang.org/> and https://github.com/chrismichaelps/pudu-lang-docgen
![The Pudu logo](../../images/pudu-lang-short.png "Pudu")

Configuration reference <https://www.pudu-lang.org/> and https://github.com/chrismichaelps/pudu-lang-docgen


Images that point at a YouTube or Vimeo page, or at a .mp4, .webm, .ogg, .ogv, or .mov file, are embedded as video players.

Tables

Pipe tables support left, center, and right alignment.

| Setting | Type | Default |
|:--------|:----:|--------:|
| `output` | text | `_site` |
| `dryRun` | flag | `false` |

Code blocks

Fenced code blocks are colored by language, labeled with the language name, and carry a copy button. Languages are recognized by name, alias, file extension, or file name.

fn greet(name: Str) -> Str { "Hello, " + name }

fn greet(name: Str) -> Str { "Hello, " + name }

Code excerpts

Excerpts show part of another file so that samples stay in sync with code that compiles. The path is relative to the article.

[!code-pudu[](samples/Inventory.pudu#apply?highlight=4-6 "Applying a change")]

!code-pudu[]

The :::code directive writes the same selection as attributes:

:::code language="pudu" source="samples/Inventory.pudu" id="types" title="Inventory types":::

:::code language="pudu" source="samples/Inventory.pudu" id="types" title="Inventory types":::

Includes

A whole-line include places the blocks of another Markdown file where it stands. An inline include places the content of a short file inside a sentence. Includes may nest; a cycle is reported as DG103.

[!INCLUDE[Package modules](includes/package-modules.md)]

The package name is [!include[name](includes/package-name.md)].

!INCLUDE[Package modules]

The package name is !include[name].

[!TIP] Keep included files out of the content globs, as this site does with exclude, so they are not also published as pages of their own.

Alerts

A quote whose first line is [!KIND] becomes an alert. The built-in kinds are NOTE, TIP, IMPORTANT, CAUTION, and WARNING. Other kinds are declared in markdownEngineProperties.alerts with the CSS classes they use.

> [!NOTE]
> Information the reader should notice.

[!NOTE] Information the reader should notice.

[!TIP] Optional advice that helps the reader succeed.

[!IMPORTANT] Information required for success.

[!CAUTION] Negative consequences of an action.

[!WARNING] Dangerous consequences that need immediate attention.

This site declares a SECURITY kind styled like a caution:

"markdownEngineProperties": { "alerts": { "SECURITY": "alert alert-caution" } }

[!SECURITY] Never commit credentials to a documentation repository.

An unknown kind is reported with DG107 and rendered as an ordinary quote.

Tabs

A tab group is a run of headings written as links to #tab/<id>, ended by a line holding only --- or ***. Tabs with the same id switch together across every group on the page. A tab written #tab/<id>/<condition> is shown only while the tab with id <condition> is selected in another group.

# [macOS](#tab/macos)

open _site/index.html

# [Linux](#tab/linux)

xdg-open _site/index.html

---

macOS

open _site/index.html

Linux

xdg-open _site/index.html

Selecting a tab above also selects the tab with the same id here:

macOS

Uses the open command.

Linux

Uses the xdg-open command.

Rows and columns

:::row::: lays out :::column::: blocks side by side. span="2" makes a column twice as wide. Columns wrap on narrow screens.

:::row:::
:::column:::
**Content** is what readers see.
:::column-end:::
:::column span="2":::
**Resources** are copied as they are. This column is twice as wide.
:::column-end:::
:::row-end:::

:::row::: :::column::: Content is what readers see. :::column-end::: :::column span="2"::: Resources are copied as they are. This column is twice as wide. :::column-end::: :::row-end:::

Image directive

The :::image directive places a figure with a larger image to open (lightbox). Its type is content (the default), icon (decorative, published without alternate text), or complex, which takes a long description up to :::image-end::: and shows it in a disclosure.

:::image type="content" source="../../images/pudu-lang-short.png" alt-text="The Pudu logo" lightbox="../../images/pudu-lang-short.png":::

:::image type="content" source="../../images/pudu-lang-short.png" alt-text="The Pudu logo" lightbox="../../images/pudu-lang-short.png":::

:::image type="complex" source="../../images/pudu-lang-short.png" alt-text="The Pudu logo":::
A letter P built from two shapes: a wide rounded bar in medium blue across the top and a narrower light blue stem below it on the left.
:::image-end:::

:::image type="complex" source="../../images/pudu-lang-short.png" alt-text="The Pudu logo"::: A letter P built from two shapes: a wide rounded bar in medium blue across the top and a narrower light blue stem below it on the left. :::image-end:::

Video

A quote holding only [!Video address], or the :::video source="address"::: directive, embeds a player. The address must use HTTPS; otherwise the build reports DG126.

> [!Video https://www.youtube-nocookie.com/embed/VIDEO_ID]

:::video source="https://player.vimeo.com/video/VIDEO_ID":::

Math

Inline math is written between single dollar signs and display math between $$ lines. Pages that use math load a TeX renderer.

The area of a circle is $A = \pi r^2$.

$$
\sum_{k=1}^{n} k = \frac{n(n+1)}{2}
$$

The area of a circle is $A = \pi r^2$.

$$ \sum_{k=1}^{n} k = \frac{n(n+1)}{2} $$

Diagrams

A mermaid code block is drawn as a diagram in the browser, following the light or dark color theme.

sequenceDiagram Author->>Build: docgen build Build->>Build: validate every page Build-->>Author: site written to _site

sequenceDiagram
  Author->>Build: docgen build
  Build->>Build: validate every page
  Build-->>Author: site written to _site

A plantuml code block is drawn by a PlantUML server. The public server is used unless markdownEngineProperties.plantUml names another server or asks for local rendering.

@startuml Author -> Build : docgen build Build --> Author : _site @enduml

@startuml
Author -> Build : docgen build
Build --> Author : _site
@enduml

Footnotes

The build validates links before writing.[^validation]

[^validation]: Links, images, fragments, and cross references are all checked.

The build validates links before writing.[^validation]

Emoji

Short codes cover every fully qualified emoji: Unicode names in lower case joined by underscores, plus common aliases.

:tada: :rocket: :white_check_mark: :thumbs_up_medium_skin_tone:

:tada: :rocket: :white_check_mark: :thumbs_up_medium_skin_tone:

Entities and raw HTML

Named and numeric character references are decoded: © → € renders as &copy; &rarr; &#8364;.

Allowed HTML elements keep their safe attributes:

<details>
<summary>Show the build output</summary>
<p>Build succeeded: 42 written, 0 unchanged, 0 removed.</p>
</details>

Build succeeded: 42 written, 0 unchanged, 0 removed.

Cross references

<xref:uid>, @uid, and [text](xref:uid) link to any page or declaration by identity. For example, <xref:PuduLangDocgen.Docset.build> and [the build plan](xref:PuduLangDocgen.Build.plan). See Links and cross references for every form.

[^validation]: Links, images, fragments, and cross references are all checked.