Diátaxis schema

Built-in id: diataxis:diataxis:1.0

Published at: https://hawkeyexl.github.io/manni/schemas/diataxis/1.0.json

Requires type and constrains it to the four Diátaxis forms.

It is one of the taxonomy schemas, which fix a classification key to a published set of values. google:okf:0.1 requires a type but accepts any non-empty string. This schema stops how-to, howto and guide from all meaning the same thing. The framework itself is documented at diataxis.fr.

Use it

Diátaxis is not part of the default set. It both requires and constrains type, so applying it by default would fail every repo not already using Diátaxis. Opt in with -s or a schemas: entry in config.

manni.config.yaml

meta:
  schemas:
    - diataxis:diataxis:1.0
    - google:okf:0.1

The pair checks type against the vocabulary and the other OKF fields for format. To try it once without config:

manni meta validate docs/ -s diataxis:diataxis:1.0

Fields

Field	Type	Required	Values
type	string	Yes	tutorial, how-to, reference, explanation

Value	Orientation
tutorial	Learning-oriented
how-to	Task-oriented
reference	Information-oriented
explanation	Understanding-oriented

Additional properties

Allowed. The schema says nothing about any key but type, so a page may carry whatever else it needs.

Example

---
type: how-to
title: Rotate an API key
---

A common mistake

A near-miss spelling is the usual failure. type: guide reads naturally and is not one of the four forms:

✗ docs/rotate-keys.md
    /type  must be equal to one of the allowed values  (line 2)  [diataxis:diataxis:1.0]

A page with no type at all fails too, because the key is required. The taxonomy schemas overview covers retrofitting an existing docs set, and why this schema and tgdp:templates:1.0 are alternatives rather than a pair.