Skip to content

Commit

Permalink
docs: change Diataxis categories to the standard order (#559)
Browse files Browse the repository at this point in the history
The Diataxis categories in Pebble are currently ordered: Tutorial,
How-to guides, Explanation, Reference. The standard order should be
Tutorial, How-to guides, _Reference, Explanation_.

The 2x2 grid of cards on the homepage actually has the correct layout
(matching the [Diataxis map](https://diataxis.fr/_images/diataxis.png)):

```
Tutorial     How-to guides
Explanation  Reference
```

This PR:

- Reorders the Diataxis categories to Tutorial, How-to guides,
Reference, Explanation.
- Uses `:reverse:` in the grid source to swap Reference and Explanation,
instead of ordering them as Explanation > Reference in the grid source.
We need to do it this way so that Reference stacks above Explanation if
the browser window is narrow.

In short, we're matching how Ops is set up. See
https://github.com/canonical/operator/blob/main/docs/index.md?plain=1#L54
  • Loading branch information
dwilding authored Jan 16, 2025
1 parent 3b8127b commit ddf828d
Showing 1 changed file with 8 additions and 7 deletions.
15 changes: 8 additions & 7 deletions docs/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,18 +24,19 @@ Pebble is useful for developers who are building [Juju charms on Kubernetes](htt
````

````{grid} 1 1 2 2
```{grid-item-card} [Explanation](explanation/index)
**Discussion and clarification** of key topics
- [General model](explanation/general-model.md)
- [API and clients](explanation/api-and-clients.md)
```
:reverse:
```{grid-item-card} [Reference](reference/index)
**Technical information**
- [Layer specification](reference/layer-specification)
- [CLI commands](reference/cli-commands)
- [Pebble in containers](reference/pebble-in-containers)
```
```{grid-item-card} [Explanation](explanation/index)
**Discussion and clarification** of key topics
- [General model](explanation/general-model.md)
- [API and clients](explanation/api-and-clients.md)
```
````

## Releases
Expand All @@ -60,6 +61,6 @@ The Pebble project is sponsored by [Canonical Ltd](https://www.canonical.com).
:diataxis:Tutorial <tutorial/getting-started>
:diataxis:how-to/index
:diataxis:explanation/index
:diataxis:reference/index
:diataxis:explanation/index
```

0 comments on commit ddf828d

Please sign in to comment.