dokt

dokt lets you turn Markdown files already scattered through a project into a documentation site. It's configured using a single file in your project root, and will:

It's one small binary with no runtime dependencies. The generated site is built to work on any host, whether it be locally hosted, on a cloud fileshare, or used as a public documentation website. To see a demo or find more information you can view the full docs here, which are generated with dokt.

Contents

See Also

Installation

npm

There are two ways to install using npm:

npx @sortofrad/dokt init   # you do not need to add `dokt` as a dependency to use it

# or

npm install --save-dev @sortofrad/dokt
npx dokt init    # adding as a dependency allows you to use the shorter name

It's recommended to add dokt as a dependency for ease of use, but you do not have to.

cargox

It's recommended to use dokt through cargox for Rust projects:

carogx dokt init

And that's it. You can install dokt as a dependency with cargo install --dev dokt but there isn't any benefit to doing so.

Source

To install from source you need Rust 1.89 or newer.

cargo build --release

The compiled binary can be found at target/release/dokt. You can test it out on the source itself:

./target/release/dokt serve

Quick start

cd my-project
dokt init          # writes dokt.toml with every setting explained
dokt serve         # http://127.0.0.1:3000, rebuilds and reloads as you edit
dokt export --web  # the static site, in dokt-out/ by default
dokt export --pdf  # one PDF, dokt-out/<title>.pdf

dokt.toml marks the project root. An empty file is valid, every option has a default it will fall back to. By default every Markdown file in the project becomes a page, and by default node_modules/, .git/, and target/ are ignored. You can find a full list configuration options and default values here.

Commands

Every command finds dokt.toml in the current directory or the nearest parent. Use --config path/to/dokt.toml (or -c) to point at a different one.

Command Behavior
dokt init [--force] Write a starter dokt.toml that sets every default value explicitly, explaining each one.
dokt serve [--host H] [--port P] [--out DIR] Build and serve (default 127.0.0.1:3000), rebuild when files change
dokt build [--out DIR] [--strict] Build the static site. The same as export --web.
dokt export [--web [DIR]] [--pdf [FILE]] [options] Export as a static site, a PDF, or both. See.

--strict (on build and export) turns warnings such as broken links into a failing exit code, which is useful in CI. serve notices changes by re-scanning once a second, and also picks up edits to dokt.toml, your stylesheets, and your logo.

Keyboard Navigation

The generated website comes with a number of keybinds for easy keyboard navigation.

Key Action
? show this shortcut list
/ or Ctrl+k or Cmd+k focus the page filter
↑ ↓ move through filter results
Enter open the highlighted result (the first one by default). Ctrl+Enter/Cmd+Enter opens in a new tab
Esc clear the filter
[ ] previous / next page, in sidebar order
g h navigate to the home page
g t navigate to the TODOs page
t cycle the theme

The filter matches every word you type against page titles and paths. Shortcuts are ignored while you are typing in a field. The first Tab stop on every page is a "Skip to content" link.

Configuration reference

Every key is optional. Unknown keys are an error, so typos do not pass silently. Run dokt init for a commented starting file.

Key Default Meaning
title folder name shown in the sidebar, page titles and PDF cover
out_dir "dokt-out" where build, serve and export write
include ["**"] globs of files to consider
exclude [] gitignore-style patterns to skip
default_excludes true also skip node_modules/, .git/, /target/
respect_gitignore true honor .gitignore files
allow_html true allow raw HTML in Markdown
css [] paths to additional stylesheets. Imported with priority over the standard styles
[todos]
enabled true highlight and collect TODOs
markers ["TODO"] words that mark a TODO
files ["TODO.md"] file names whose every list item is a TODO
[brand]
logo none image beside the title
logo_dark none logo for the dark theme (needs logo)
favicon the logo browser tab icon
show_title true false shows only the logo
footer none plain text at the bottom of every page
[export]
paper "a4" "a4" or "letter"
browser found automatically path to Chrome, Chromium or Edge
[theme]
mode "auto" "auto", "light" or "dark"
toggle true show the theme button (only in auto mode)
[theme.light], [theme.dark] built in bg fg muted line soft accent broken todo

Known limits