Authoring guide

Install the CLI

Install dtinth/docs repository directly from GitHub. It installs a CLI tool dtinth-docs.

$ npm i -g dtinth/docs

With the CLI, one can preview how the documentation would look like on the website without having to clone the documentation site repository. The CLI package includes Antora and the UI bundle, and automatically generates the Antora playbook for editing a project documentation in isolation. This makes it ideal for documenting projects in cloud-based environments such as GitHub Codespaces.

⚠️ This CLI tool is not tested on Windows at all. It probably won’t work.

Initialize a documentation structure for a project

Run this from the repository root:

$ dtinth-docs init my-project

This command generates the following structure:

📒 <repo>
  📂 docs
    📄 antora.yml
    📂 modules/ROOT
      📄 nav.adoc
      📂 pages
        📄 index.adoc

Start the documentation preview server

Run this from the repository root:

$ dtinth-docs

Then go to http://localhost:9090/. As you make changes to the documentation, the server will automatically rebuild the documentation.

In VS Code, AsciiDoc files can also quickly be previewed using the AsciiDoc extension. This gives faster feedback but has lower fidelity.

Publishing new documentation

Add a new entry to the docs.dt.in.th spreadsheet on Google Sheets.
Rebuild the site on GitHub Actions.

Deploying documentation updates using the CLI

For converience, the deployment workflow action can be triggered from the CLI:

$ dtinth-docs deploy

After committing your changes, you can push and redeploy the site in one go:

$ git push && dtinth-docs deploy

The GitHub CLI must be installed.