docki 1.1.1

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

# Docki

> [!NOTE]
> This project is under renovations. While installing it right now might work, it is not guaranteed


## Preview

![screencast](.gitlab/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

### Nix

This installation method is recommended, because it will include both asciidoctor and asciidoctor_revealjs.

Note: This is the most basic installation. If you are already more experienced, you might want to add it to your shell or home manager configuration.

```shell
nix profile install github:quirinecker/docki
```

### Homebrew

> [!NOTE]
> Installing it via homebrew will not include asciidoctor_revealjs. It can be installed afterwards with `docki install-reveal`

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

```
brew install docki
```

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


### 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
]
```

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