How to Publish Documentation From Markdown

Documentation ages well in Markdown: it is easy to write, easy to review and easy to keep next to the thing it documents. This guide publishes a set of Markdown files as a documentation page with sections, using Sentilis Press.

One entry, several pages

In Sentilis, a documentation set is a folder with an index.md. The index.md is the main page; every other .md file next to it becomes a section of it:

press/
└── api-guide/
    ├── index.md              ← overview (main page)
    ├── authentication.md     ← section
    ├── errors.md             ← section
    └── attachments/
        ├── cover.png
        └── flow.png

Sections are one level deep: there are no sections of sections. For a larger set of docs, publish several entries — one per topic — and link between them with their full URLs.

Write the main page

---
name: API guide
category: Documentation
tags: api, reference
---

# API guide

Everything you need to make your first request.

- [Authentication](./authentication.md)
- [Errors](./errors.md)

Links between pages of the same entry use the file name, as above. Links to anything else use a full https:// address.

Sections inherit visibility

Sections take status, visibility and password from index.md, so a private set of docs does not leak through one of its pages. Set those fields on a section to override them. Everything else — category, tags — is set per page.

Images and diagrams

Every local image lives in the entry’s attachments/ folder, with sub-folders allowed. Reference images from any page of the entry:

![Request flow](./attachments/flow.png "How a request is authenticated")

A cover.png in attachments/ is used when the docs are shared. All the media of the entry, sections included, must add up to 5 MB or less.

Publish and keep it current

sentilis sync ./my-content

Update a page, run the sync again, and the entry is updated in place. Keeping the docs in Git makes every change reviewable — see docs as code for publishing on every merge.

Tips for docs that stay useful

Start with the task. The overview should say what the reader can do after reading.
One topic per section. Short sections are easier to link to and to keep accurate.
Date nothing you don’t maintain. Prefer stable explanations over “as of” statements.

Publish your Markdown docs →