Docki

Preview

Docki is cli for converting asciidoctor files into html files.

Usage

Docki must be run in a directory with the following structure

1. Will be converted into asciidoc format
2. Will be converted into asciidocs slides

Note

The input directory can be defined either with a cli argument or the config file. Default is ./docs

Building the documentation

docki build

Serving the documentation with a live server

docki serve

Installation

Homebrew

brew tap quirinecker/homebrew-docki https://github.com/quirinecker/homebrew-docki

brew install docki

Nix

If you just want to try it out real quick and the nix package manager is available on your system you can use the following command.

nix develop github:quirinecker/docki#preview

This will open a shell evnironment with docki installed. If you want to install it permanently with nix, i would recommend following the instructions in the Nix (Advanced, Flake) section.

Cargo

Note

This is the most basic installation. It will not include asciidoctor_revealjs and asciidoctor itself. Installing asciidoctor has to be done manually, while installing asciidoctor_revealjs can be done with docki install-reveal

cargo install docki

Docker

There is also a docker image available to use. It is primarily used for the gh actions.

docker pull ghcr.io/quirinecker/docki:latest

You can also build it yourself with nix.

nix build .#docker && docker load -i result

Nix (Advanced, Flake)

Note

There are multiple ways to install docki with nix. This is the way I installed it on my machine.

1. Add it to the flake inputs

docki = {
	url = "github:quirinecker/docki";
	inputs.nixpkgs.follows = "nixpkgs";
};

2. Add @inputs at the end of the outputs (if you haven't already)

outputs = {
	nixpkgs
	...
}@inputs:
...Rest of your flake...

3. Add the input to your system packages (system configuration) or home packages (home manager configuration)

environment.systemPackages = with pkgs; [
	inputs.docki.packages.${system}.default
]

or

home.packages = with pkgs; [
	inputs.docki.packages.${system}.default
]

Configuration

You can configure some of the cli arguments with a config file. It is always located relatively to the current directory under ./docki.config.toml. Available options and their defaults can be found in the docki.config.toml file. CLI arguments with the same names as in the config usually have also the same default values. As a fallback you can also use the config.rs file for reference.

Development

Running it

If you just want to run it, you can use the nix run command. This will install all the build dependencies, build the binary and run it.

nix run

Development Shell

You can also use the development shell with the command below. In this shell all dependencies for building and running the project are installed.

nix develop

Afterwards it can be built and run with cargo

cargo run -- <args>