docki 1.3.0

cli for building and publishing documentation using asciidoctor
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142

# Docki

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


## Preview

![screencast](.github/assets/screencast.gif)

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

```shell
docki build
```

### Serving the documentation on a live server

```shell
docki serve
```

## Installation

### Homebrew

```shell
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.

```shell
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)](#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`

```shell
cargo install docki
```

### Docker

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

```shell
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

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

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

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

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

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

or

```nix
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](config/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](src/app/config/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.

```shell
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.

```shell
nix develop
```

Afterwards it can be built and run with cargo

```shell
cargo run -- <args>
```