dokk

Command line

Terminal
dokk init     # scaffold a new site
dokk serve    # write with live reload
dokk check    # find broken links before you publish
dokk format   # tidy the Markdown of every page
dokk build    # build the production site

Every command takes --root PATH, the folder with dokk.toml; it defaults to the current folder. dokk --version prints the version.

dokk init #

Scaffolds a new site in --root.

  • dokk.tomltitle and settings
  • docs/
    • index.mdthe home page
  • .gitignoreignores .dokk/
  • .github/
    • workflows/
      • docs.ymlbuilds and deploys to GitHub Pages
--root PATH
Where to create the site. Default: the current folder.
Note

init never overwrites. If any of these files exist, it stops and lists them. The exception is .gitignore: in an existing project, init adds .dokk/ to it.

dokk serve #

Builds into .dokk/dev/, serves it and rebuilds when you save. The browser reloads on its own. Stop it with Ctrl+C.

Terminal
dokk serve --port 8001 --search
--port PORT
Port on 127.0.0.1. Default: 8002.
--search
Build the search index on every rebuild. Off by default, because indexing makes rebuilds slower.
-v, --verbose
Log each step of every rebuild and how long it took, as dokk build -v does.
--root PATH
The site folder. Default: the current folder.

Draft pages are included, and the base path from site_url is ignored, so links work on localhost. A build error shows in the browser and clears on the next good save.

Caution

serve is for writing, not hosting. Publish the output of dokk build.

dokk check #

Builds the production site into a temporary folder and reports problems:

  • links to missing pages, files or anchors
  • pages without a title, more than one <h1>, or skipped heading levels
  • with [[sidebar]] in dokk.toml: pages missing from the sidebar
Terminal
dokk check
--root PATH
The site folder. Default: the current folder.
Tip

check exits with status 1 when it finds errors, so it can stop a CI run. The workflow from dokk init runs it before every deploy.

dokk build #

Builds the production site into out_dir (default .dokk/build/), with the search index when the search extra is installed. Broken links are printed as warnings.

Terminal
dokk build --drafts
--drafts

Include pages with draft: true.

-v, --verbose

Log each build step when it starts and how long it took, to find what makes a build slow:

19:36:12.582 markdown (44 pages) ...
19:36:13.000 markdown (44 pages): 418 ms
19:36:13.000 write pages ...
19:36:13.152 write pages: 152 ms
--root PATH

The site folder. Default: the current folder.

Builds are deterministic: the same input gives byte-identical output. When site_url has no path, you can look at a build locally with python -m http.server 8000 -d .dokk/build. With a path, such as GitHub Pages’ /my-docs/, links only work once deployed; use dokk serve locally.

dokk format #

Formats every page in the content folder with mdformat, so lists, tables and spacing look the same everywhere. It knows dokk’s Markdown: front matter, components, tables, footnotes and definition lists are kept intact, and the lines in :::env and :::bench stay exactly as written.

Terminal
pip install "dokk[format]"
dokk format
--check
Change nothing; list the pages that are not formatted and exit with an error. Use it in CI or a pre-commit hook.
--root PATH
The site folder. Default: the current folder.