From c92ba4b9b7b63f24050c8e769a102380ea079e4f Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Fri, 17 Oct 2025 21:50:31 +0200
Subject: [PATCH] Add titles in JSON schemas

This way, the description isn't rendered in the tables of contents,
leading to no more formatting errors.
---
 .../protocols/json/schema/derivation-v3.yaml       | 14 ++++++++++++++
 .../source/protocols/json/schema/hash-v1.yaml      |  1 +
 2 files changed, 15 insertions(+)

diff --git a/doc/manual/source/protocols/json/schema/derivation-v3.yaml b/doc/manual/source/protocols/json/schema/derivation-v3.yaml
index e80f24e9f..7c92d475d 100644
--- a/doc/manual/source/protocols/json/schema/derivation-v3.yaml
+++ b/doc/manual/source/protocols/json/schema/derivation-v3.yaml
@@ -26,12 +26,14 @@ required:
 properties:
   name:
     type: string
+    title: Derivation name
     description: |
       The name of the derivation.
       Used when calculating store paths for the derivation’s outputs.
 
   version:
     const: 3
+    title: Format version (must be 3)
     description: |
       Must be `3`.
       This is a guard that allows us to continue evolving this format.
@@ -49,6 +51,7 @@ properties:
 
   outputs:
     type: object
+    title: Output specifications
     description: |
      Information about the output paths of the derivation.
      This is a JSON object with one member per output, where the key is the output name and the value is a JSON object as described.
@@ -69,6 +72,7 @@ properties:
 
   inputSrcs:
     type: array
+    title: Input source paths
     description: |
       List of store paths on which this derivation depends.
 
@@ -85,6 +89,7 @@ properties:
 
   inputDrvs:
     type: object
+    title: Input derivations
     description: |
       Mapping of derivation paths to lists of output names they provide.
 
@@ -101,12 +106,14 @@ properties:
 
   system:
     type: string
+    title: Build system type
     description: |
       The system type on which this derivation is to be built
       (e.g. `x86_64-linux`).
 
   builder:
     type: string
+    title: Build program path
     description: |
       Absolute path of the program used to perform the build.
       Typically this is the `bash` shell
@@ -114,6 +121,7 @@ properties:
 
   args:
     type: array
+    title: Builder arguments
     description: |
       Command-line arguments passed to the `builder`.
     items:
@@ -121,12 +129,14 @@ properties:
 
   env:
     type: object
+    title: Environment variables
     description: |
       Environment variables passed to the `builder`.
     additionalProperties:
       type: string
 
   structuredAttrs:
+    title: Structured attributes
     description: |
       [Structured Attributes](@docroot@/store/derivation/index.md#structured-attrs), only defined if the derivation contains them.
       Structured attributes are JSON, and thus embedded as-is.
@@ -139,11 +149,13 @@ properties:
     properties:
       path:
         type: string
+        title: Output path
         description: |
           The output path, if known in advance.
 
       method:
         type: string
+        title: Content addressing method
         enum: [flat, nar, text, git]
         description: |
           For an output which will be [content addressed](@docroot@/store/derivation/outputs/content-address.md), a string representing the [method](@docroot@/store/store-object/content-address.md) of content addressing that is chosen.
@@ -156,9 +168,11 @@ properties:
           - [`git`](@docroot@/store/store-object/content-address.md#method-git)
 
       hashAlgo:
+        title: Hash algorithm
         "$ref": "./hash-v1.yaml#/$defs/algorithm"
 
       hash:
         type: string
+        title: Expected hash value
         description: |
           For fixed-output derivations, the expected content hash in base-16.
diff --git a/doc/manual/source/protocols/json/schema/hash-v1.yaml b/doc/manual/source/protocols/json/schema/hash-v1.yaml
index b258a90c7..44a59541b 100644
--- a/doc/manual/source/protocols/json/schema/hash-v1.yaml
+++ b/doc/manual/source/protocols/json/schema/hash-v1.yaml
@@ -10,6 +10,7 @@ description: |
 type: object
 properties:
   algorithm:
+    title: Hash algorithm
     "$ref": "#/$defs/algorithm"
 required:
 - algorithm