Docs as Code: Publish Documentation on Every Merge

Docs as code means writing documentation with the same tools and workflow as software: plain text files, version control, reviews and automation. Markdown in a Git repository is the most common way to do it.

Why teams do it

Reviews. Documentation changes go through pull requests, like code.
History. Every change has an author, a date and a reason.
Proximity. Docs live next to the code they describe, so they change together.
Automation. Validation and publishing happen without anyone clicking publish.

The workflow

Write or edit Markdown in your editor.
Open a pull request.
CI validates the content.
On merge, CI publishes it.

With Sentilis, steps 3 and 4 are two runs of the same CLI command.

Validate without publishing

--dry-run checks every entry in the folder without uploading anything. It is a good check for pull requests:

sentilis sync ./docs --dry-run

Publish on merge, all or nothing

--strict aborts the whole run if any entry has a validation problem, so a bad file fails the pipeline instead of publishing half a change:

sentilis sync ./docs --strict

Authenticate first with sentilis auth login and your profile token. In CI, store the token as a secret rather than in the repository.

Repository layout

repo/
├── src/
└── docs/
    └── press/
        └── user-guide/
            ├── index.md
            ├── install.md
            ├── configuration.md
            └── attachments/

user-guide/ is one entry: index.md is the main page and the other files are its sections. Add more entries next to it for other topics.

A note on drafts

Mark pages status: draft while they are in progress. They can be merged without appearing on the site, and published later by changing the status to published.

Next steps

Set up the pipeline with GitHub Actions.
Learn the rest of the CLI in publishing from the command line.

Write in VS Code, publish from CI →