Add meta description tag to docs pages (#35112)

Closes #ISSUE Adds basic frontmatter support to `.md` files in docs. The only supported keys currently are `description` which becomes a `<meta name="description" contents="...">` tag, and `title` which becomes a normal `title` tag, with the title contents prefixed with the subject of the file. An example of the syntax can be found in `git.md`, as well as below ```md --- title: Some more detailed title for this page description: A page-specific description --- # Editor ``` The above will be transformed into (with non-relevant tags removed) ```html <head> <title>Editor | Some more detailed title for this page</title> <meta name="description" contents="A page-specific description"> </head> <body> <h1>Editor</h1> </body> ``` If no front-matter is provided, or If one or both keys aren't provided, the title and description will be set based on the `default-title` and `default-description` keys in `book.toml` respectively. ## Implementation details Unfortunately, `mdbook` does not support post-processing like it does pre-processing, and only supports defining one description to put in the meta tag per book rather than per file. So in order to apply post-processing (necessary to modify the html head tags) the global book description is set to a marker value `#description#` and the html renderer is replaced with a sub-command of `docs_preprocessor` that wraps the builtin `html` renderer and applies post-processing to the `html` files, replacing the marker value and the `<title>(.*)</title>` with the contents of the front-matter if there is one. ## Known limitations The front-matter parsing is extremely simple, which avoids needing to take on an additional dependency, or implement full yaml parsing. * Double quotes and multi-line values are not supported, i.e. Keys and values must be entirely on the same line, with no double quotes around the value. The following will not work: ```md --- title: Some Multi-line Title --- ``` * The front-matter must be at the top of the file, with only white-space preceding it * The contents of the title and description will not be html-escaped. They should be simple ascii text with no unicode or emoji characters Release Notes: - N/A *or* Added/Fixed/Improved ... --------- Co-authored-by: Katie Greer <katie@zed.dev>
2025-07-29 23:01:03 +00:00
parent 57766199cf
commit 3824751e61
9 changed files with 318 additions and 49 deletions
@@ -69,3 +69,64 @@ Templates are just functions that modify the source of the docs pages (usually w
 - Template Trait: crates/docs_preprocessor/src/templates.rs
 - Example template: crates/docs_preprocessor/src/templates/keybinding.rs
 - Client-side plugins: docs/theme/plugins.js
+
+## Postprocessor
+
+A postprocessor is implemented as a sub-command of `docs_preprocessor` that wraps the builtin `html` renderer and applies post-processing to the `html` files, to add support for page-specific title and meta description values.
+
+An example of the syntax can be found in `git.md`, as well as below
+
+```md
+---
+title: Some more detailed title for this page
+description: A page-specific description
+---
+
+# Editor
+```
+
+The above will be transformed into (with non-relevant tags removed)
+
+```html
+<head>
+  <title>Editor | Some more detailed title for this page</title>
+  <meta name="description" contents="A page-specific description" />
+</head>
+<body>
+  <h1>Editor</h1>
+</body>
+```
+
+If no front-matter is provided, or If one or both keys aren't provided, the title and description will be set based on the `default-title` and `default-description` keys in `book.toml` respectively.
+
+### Implementation details
+
+Unfortunately, `mdbook` does not support post-processing like it does pre-processing, and only supports defining one description to put in the meta tag per book rather than per file. So in order to apply post-processing (necessary to modify the html head tags) the global book description is set to a marker value `#description#` and the html renderer is replaced with a sub-command of `docs_preprocessor` that wraps the builtin `html` renderer and applies post-processing to the `html` files, replacing the marker value and the `<title>(.*)</title>` with the contents of the front-matter if there is one.
+
+### Known limitations
+
+The front-matter parsing is extremely simple, which avoids needing to take on an additional dependency, or implement full yaml parsing.
+
+- Double quotes and multi-line values are not supported, i.e. Keys and values must be entirely on the same line, with no double quotes around the value.
+
+The following will not work:
+
+```md
+---
+title: Some
+  Multi-line
+  Title
+---
+```
+
+And neither will:
+
+```md
+---
+title: "Some title"
+---
+```
+
+- The front-matter must be at the top of the file, with only white-space preceding it
+
+- The contents of the title and description will not be html-escaped. They should be simple ascii text with no unicode or emoji characters
@@ -6,13 +6,27 @@ src = "src"
 title = "Zed"
 site-url = "/docs/"

-[output.html]
+[build]
+extra-watch-dirs = ["../crates/docs_preprocessor"]
+
+# zed-html is a "custom" renderer that just wraps the
+# builtin mdbook html renderer, and applies post-processing
+# as post-processing is not possible with mdbook in the same way
+# pre-processing is
+# The config is passed directly to the html renderer, so all config
+# options that apply to html apply to zed-html
+[output.zed-html]
+command = "cargo run -p docs_preprocessor -- postprocess"
+# Set here instead of above as we only use it replace the `#description#` we set in the template
+# when no front-matter is provided value
+default-description = "Learn how to use and customize Zed, the fast, collaborative code editor. Official docs on features, configuration, AI tools, and workflows."
+default-title = "Zed Code Editor Documentation"
 no-section-label = true
 preferred-dark-theme = "dark"
 additional-css = ["theme/page-toc.css", "theme/plugins.css", "theme/highlight.css"]
 additional-js  = ["theme/page-toc.js", "theme/plugins.js"]

-[output.html.print]
+[output.zed-html.print]
 enable = false

 # Redirects for `/docs` pages.
@@ -24,7 +38,7 @@ enable = false
 # The destination URLs are interpreted relative to `https://zed.dev`.
 # - Redirects to other docs pages should end in `.html`
 # - You can link to pages on the Zed site by omitting the `/docs` in front of it.
-[output.html.redirect]
+[output.zed-html.redirect]
 # AI
 "/ai.html" = "/docs/ai/overview.html"
 "/assistant-panel.html" = "/docs/ai/agent-panel.html"
@@ -1,3 +1,8 @@
+---
+description: Zed is a text editor that supports lots of Git features
+title: Zed Editor Git integration documentation
+---
+
 # Git

 Zed currently offers a set of fundamental Git features, with support coming in the future for more advanced ones, like conflict resolution tools, line by line staging, and more.
@@ -15,7 +15,7 @@
        <!-- Custom HTML head -->
        {{> head}}

-        <meta name="description" content="{{ description }}">
+        <meta name="description" content="#description#">
        <meta name="viewport" content="width=device-width, initial-scale=1">
        <meta name="theme-color" content="#ffffff">