3824751e61
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>
27 lines
527 B
TOML
27 lines
527 B
TOML
[package]
|
|
name = "docs_preprocessor"
|
|
version = "0.1.0"
|
|
edition.workspace = true
|
|
publish.workspace = true
|
|
license = "GPL-3.0-or-later"
|
|
|
|
[dependencies]
|
|
anyhow.workspace = true
|
|
command_palette.workspace = true
|
|
gpui.workspace = true
|
|
mdbook = "0.4.40"
|
|
regex.workspace = true
|
|
serde.workspace = true
|
|
serde_json.workspace = true
|
|
settings.workspace = true
|
|
util.workspace = true
|
|
workspace-hack.workspace = true
|
|
zed.workspace = true
|
|
zlog.workspace = true
|
|
|
|
[lints]
|
|
workspace = true
|
|
|
|
[[bin]]
|
|
name = "docs_preprocessor"
|
|
path = "src/main.rs"
|