Overview

Djockey is an experimental but powerful static site generator for technical writing and project documentation. The goal is to have the depth and extensibility of Sphinx with the ease-of-use and built-in power of Material for MkDocs.

Write Djot or GitHub Flavored Markdown
Output HTML or Markdown, so your docs are readable in the GitHub interface or on a nice web site
Rich cross-references, checked at build time
Tree-based plugins—stop writing Markdown tokenizer hacks!
De-emphasizes client-side JS, has a small core and a few small dependencies

Installation

You can invoke djockey directly with npx or bunx.

Node

Bun

npx djockey path/to/docs

bunx djockey path/to/docs

or install it in your JS project and then run it:

Node

Bun

`package.json`

npm install djockey
npm exec -- djockey path/to/docs

bun install djockey
bunx djockey path/to/docs

{
  "scripts": {
    "docs": "djockey path/to/docs"
  }
}

Pandoc

In order to use Markdown, you must also install Pandoc.

Simple config file

Suppose your project layout looks something like this:

docs/
  index.djot
html_output/

To render docs/ into html_output/, you would put a file in your repo root called djockey.yaml with these contents:

input_dir: docs
output_dir:
  html: html_output
site_name: "Your Name Here"
url_root: https://where-docs-will-be-deployed

Run Djockey

You can build your site for local-only viewing without a web server using file URLs like this:

npx djockey path-to-docs-directory --local

Or build for deployment on the web:

npx djockey path-to-docs-directory

Markdown output

If you add an output_dir.gfm value to your djockey.yaml, you can run Djockey with -f gfm to get Markdown output.

input_dir: docs
output_dir:
  html: html_output
  gfm: markdown_output
site_name: "Your Name Here"
url_root: https://where-docs-will-be-deployed

npx djockey docs-input-dir -f gfm