From b4946d5298b0afa85b2717c0c6424633c8e63d98 Mon Sep 17 00:00:00 2001
From: Jon Ludlam <jon@recoil.org>
Date: Mon, 17 Mar 2025 18:50:47 +0000
Subject: [PATCH] Update docs

---
 doc/driver/index.mld     |  2 +-
 doc/json.mld             |  4 +++-
 doc/odoc_for_authors.mld | 16 ++++++++++++++++
 3 files changed, 20 insertions(+), 2 deletions(-)

diff --git a/doc/driver/index.mld b/doc/driver/index.mld
index e9d09d2dee..e5ebe8cbff 100644
--- a/doc/driver/index.mld
+++ b/doc/driver/index.mld
@@ -50,7 +50,7 @@ File "src/parser/odoc_parser.mli", line 45, characters 30-45:
 Warning: Failed to resolve reference unresolvedroot(parse_coment) Couldn't find "parse_coment"
 ]}
 
-which highlights 
+which here is highlighting an error in a reference in `odoc_parser.mli`.
 
 {2 Remapping dependencies}
 
diff --git a/doc/json.mld b/doc/json.mld
index 90156b9083..4a43fc0c33 100644
--- a/doc/json.mld
+++ b/doc/json.mld
@@ -12,11 +12,12 @@ In addition, there is a per-package 'global' sidebar json file.
 
 {@json[
 {
+  "header": "<h1>Module <code><span>Stdlib</span></code><a href=\"../../src/stdlib/stdlib.ml.html\" class=\"source_link\">Source</a></h1>",
   "type": "documentation",
   "uses_katex": false,
   "breadcrumbs": [
     {
-      "name": "🏠",
+      "name": "Package index",
       "href": "../../../index.html",
       "kind": "leaf-page"
     },
@@ -66,6 +67,7 @@ ace\" ...."
 
 The fields of the JSON are as follows:
 
+- [header] is a string containing HTML for the header of the page.
 - [type] field is either [documentation] or [source].
 - [uses_katex] is [true] if the page has math entries ([{m ...}] or [{math ...}]).
 - [breadcrumbs] is a list of breadcrumb entries with members [name], [href] and [kind]. If [href] is null then there is no index page at that location in the hierarchy. [kind] is one of
diff --git a/doc/odoc_for_authors.mld b/doc/odoc_for_authors.mld
index 13d4d5ec1d..97e095a990 100644
--- a/doc/odoc_for_authors.mld
+++ b/doc/odoc_for_authors.mld
@@ -489,6 +489,22 @@ Here is some Python code:
     return 0
 ]}
 
+{4:code_block_tags Code Block Tags}
+Code blocks may have arbitrary metadata associated with them. This metadata is
+used, for example, for selecting code blocks when extracting them from a source file via the
+[odoc extract-code] command. The metadata may also be used by other tools that
+operate on code blocks, for example, {{!https://github.com/realworldocaml/mdx}mdx}.
+
+The metadata follows immediately after the language header, and is a list of tags and bindings, separated by whitespace. Tags are simple
+keywords, and bindings are key-value pairs separated by an equals sign. If whitespace
+is needed in keys, values or tags, it should be enclosed in double quotes. For example:
+
+{v
+{@ocaml tag1 "tag 2" key1="value 1" "key 2"="value 2"[
+   ... code goes here ...
+]}
+v}
+
 {4:verbatim_blocks Verbatim Blocks}
 
 It is possible to write language agnostic code blocks, also called verbatim