Yehowshua/ZIm
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Add meta description tag to docs pages (#35112)

Browse source 
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>
This commit is contained in:
Ben Kunkle 2025-07-29 18:01:03 -05:00 • committed by GitHub
parent 57766199cf
commit 3824751e61
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
9 changed files with 318 additions and 49 deletions
Download patch file Download diff file Expand all files Collapse all files

61
docs/README.md
View file

@ -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

20
docs/book.toml
View file

@ -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"

5
docs/src/git.md
View file

@ -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.

2
docs/theme/index.hbs vendored
View file

@ -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">