mdbook-diataxis 0.1.1

A preprocessor for mdBook which helps apply the Diátaxis documentation framework
Documentation 
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

# mdbook-diataxis

A preprocessor for [mdBook][mdbook] which helps apply the [Diátaxis][diataxis] documentation framework.

## Installation

Type and run

```bash
cargo install mdbook-diataxis
```

This will build `mdbook-diataxis` from source.

## Integrating `mdbook-diataxis`

Type and run the following command with the path to your book.

```bash
mdbook-diataxis install path/to/book
```

You will see that a new `[preprocessor.diataxis]` table has been added to your `book.toml`, the `[output.html]` table has been amended to include the newly-written `diataxis.css` file.

The Diátaxis directives are now available for use!

## Usage

`mdbook-diataxis` defines the following directives.

### `{{#diataxis compass}}`

Expands to an `html` representation of the diátaxis compass.
Example:

![Diátaxis compass output example](img/compass-example.png)

The text of each part of the compass can be [configured via `book.toml`](#configuration).

### `{{#diataxis table-of-contents}}`

Expands to a table of contents listing the top-level children of the current chapter.
Example:

![Table of contents output example](img/toc-example.png)

## Configuration

The following is a configuration of `mdbook-diataxis` which modifies every available field.
This snippet is for demonstration purposes; all fields are optional.

```toml
[preprocessor.diataxis.compass.tutorials]
title = "new Tutorials title"
description = "new Tutorials description"
link = "path/to/tutorials.html"

[preprocessor.diataxis.compass.how-to-guides]
title = "new How-to guides title"
description = "new How-to guides description"
link = "path/to/how-to-guides.html"

[preprocessor.diataxis.compass.explanation]
title = "new Explanation title"
description = "new Explanation description"
link = "path/to/explanation.html"

[preprocessor.diataxis.compass.reference]
title = "new Reference title"
description = "new Reference description"
link = "path/to/reference.html"
```

## License and Author.

This project is [licensed under GPLv3](LICENSE).

This project was originally written by Ed Jones.
Thank you [jf908](https://github.com/jf908), for making the grid CSS.

[diataxis]: https://diataxis.fr
[mdbook]: https://github.com/rust-lang/mdBook