Numbered steps¶

prodockit.steps presents a procedure as numbered steps that a reader works through in order. Each step has room for a title, instructions, commands, and supporting content. A joining line makes the sequence clear on both the website and in the PDF.

Use an ordinary numbered list for a list of facts. Use prodockit.steps when the reader needs to complete one action before moving to the next.

Enable the extension¶

Add the extension to zensical.toml:

[project.markdown_extensions."prodockit.steps"]

Write a procedure¶

Copy this complete example:

/// steps

//// step | Load the key into the agent

```bash
ssh-add --apple-use-keychain ~/.ssh/id_ed25519_gitlab
```

////

//// step | Upload the public key

Paste it into your host's SSH keys page.

////

///

It renders as:

1. Load the key into the agent

   ssh-add --apple-use-keychain ~/.ssh/id_ed25519_gitlab
   

2. Upload the public key

   Paste it into your host's SSH keys page.

Opening and closing the blocks¶

This extension uses the fenced-container syntax from PyMdown Blocks. An opening fence names the block; its closing fence uses the same number of slashes without the name. Nested blocks must use a different fence length. In a numbered procedure:

• /// steps opens the complete ordered procedure; /// closes it.
• //// step opens one step; //// closes it.
• Add a title after |, as in //// step | Upload the public key.
• Leave off | and the title when a step needs only body content.

The blank line after a step header is not required for a simple paragraph, but some block content needs it. Keeping the blank lines shown in the example is the safe, consistent form for paragraphs, fenced code, admonitions, and content tabs.

Content inside a step¶

A step body is ordinary block Markdown. It can contain multiple paragraphs, code fences, admonitions, or content tabs. For example, the Build your first site walkthrough places macOS, Windows, and Linux commands in tabs inside its first two steps.

Configure numbered steps¶

There are no additional prodockit.steps settings in zensical.toml. Configure each procedure inside its /// steps Markdown block.

Continue numbering after a break¶

A long procedure can be split across sections or pages. Set start on the later block so its first step continues at the required number:

/// steps
    start: 9

//// step | Point the clone at your own project

Update the remote URL before pushing.

////

///

Options use YAML syntax. Put them directly below /// steps, with no blank line between the header and its options, and indent each option by at least four spaces. The blank line after the final option separates the options from the procedure's content.

Add an id or other HTML attributes¶

Use the Blocks API's attrs option to add attributes to the generated ordered list. This complete example combines an id with continued numbering:

/// steps
    start: 9
    attrs: {id: 'setup-continued'}

//// step | Verify the remote

Run `git remote -v` before pushing.

////

///

attrs is inherited from the underlying Blocks API rather than defined by prodockit.steps; start is the extension's only steps-specific option.

Reference¶

Each title becomes a separate paragraph before the step body. A step may have no title, but every step must be inside a steps block for the resulting HTML to be a valid ordered list.

Customise the appearance¶

Add the numbered-step styles to your project's CSS style sheet. This repository's docs/stylesheets/extra.css contains the styles used by the examples on this page.

Generated HTML¶

The first example produces this structure:

<ol class="prodockit-steps">
  <li>
    <p class="prodockit-step-title">Load the key into the agent</p>
    <pre><code>ssh-add --apple-use-keychain ~/.ssh/id_ed25519_gitlab</code></pre>
  </li>
  <li>
    <p class="prodockit-step-title">Upload the public key</p>
    <p>Paste it into your host's SSH keys page.</p>
  </li>
</ol>

The two stable class names are:

The title is an element rather than bold text, so it can be styled separately from emphasis used in the step body.

If you adapt the CSS style-sheet rules in docs/stylesheets/extra.css, retain these details:

• the joining line is positioned from the number's own size, so changing --step-size does not move the line away from the number;
• the line's ::after pseudo-element uses the same font-size as the number's ::before pseudo-element, keeping em-based measurements aligned;
• the final step has no trailing joining line.

The bootstrap quick start and Build your first site are larger working examples.

Contributors changing the generated representation should read Extension integration.