Docki

[!NOTE] This project is under renovations. It can be used, but it might not be completely stable yet.

Preview

Docki is cli for converting asciidoctor files into html files.

Usage

[!NOTE] This works in a directory with a directory called docs, which contains the asciidoctor documentation.

Building the documentation

docki build

Serving the documentation on 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>