-
-
Notifications
You must be signed in to change notification settings - Fork 1.3k
Description
Description
Consecutive occurences of examples lead to DetailsBlock::Html("") in docs.json:
{
"kind": "html",
"content": ""
}This doesn't affect the official docs, but it causes styling difficulties for downstream projects. For instance, if the downstream project wraps each content with a <div>, then this empty <div> will prevent margins of sibling HTML elements to collapse, resulting in awkward additional spaces.
I suggest removing those empty DetailsBlocks.
Example
For example, there're two consecutive examples in par.line.numbering:
typst/crates/typst-library/src/model/par.rs
Lines 746 to 767 in 16de17a
| /// How to number each line. Accepts a | |
| /// [numbering pattern or function]($numbering) taking a single number. | |
| /// | |
| /// ```example | |
| /// >>> #set page(margin: (left: 3em)) | |
| /// #set par.line(numbering: "I") | |
| /// | |
| /// Roses are red. \ | |
| /// Violets are blue. \ | |
| /// Typst is there for you. | |
| /// ``` | |
| /// | |
| /// ```example | |
| /// >>> #set page(width: 200pt, margin: (left: 3em)) | |
| /// #set par.line( | |
| /// numbering: i => if calc.rem(i, 5) == 0 or i == 1 { i }, | |
| /// ) | |
| /// | |
| /// #lorem(60) | |
| /// ``` | |
| #[ghost] | |
| pub numbering: Option<Numbering>, |
After parsing, its doc comment becomes the following in
docs.json.
"details": [
{
"kind": "html",
"content": "<p>How to number each line. Accepts a\n<a href=\"/reference/model/numbering/\">numbering pattern or function</a> taking a single number.</p>"
},
{
"kind": "example",
"content": {
"body": "<div class=\"previewed-code\">…</div>",
"title": null
}
},
{
"kind": "html",
"content": "" // 👈 Here is empty
},
{
"kind": "example",
"content": {
"body": "<div class=\"previewed-code\">…</div>",
"title": null
}
}
],You can inspect the full json of this page at https://typst-docs-web.netlify.app/en-us-v0.14.0/reference/model/par/index.json.
All examples:
$ jq '.. | select(type == "object" and has("details") and (.details|type) == "array") | { name: .name, details: [.details[] | select((.content | type) == "string" and .content == "")] } | select(.details | length > 0)' docs.json --compact-output
{"name":"match","details":[{"kind":"html","content":""}]}
{"name":"numbering","details":[{"kind":"html","content":""}]}
{"name":"style","details":[{"kind":"html","content":""},{"kind":"html","content":""}]}
{"name":"augment","details":[{"kind":"html","content":""}]}
{"name":"stroke","details":[{"kind":"html","content":""}]}Cause
I guess we should check if docs[i..fence_idx].trim() is empty here:
Lines 574 to 577 in 16de17a
| // First, push non-fenced content. | |
| if found > 0 { | |
| res.push(RawDetailsBlock::Markdown(&docs[i..fence_idx])); | |
| } |
(RawDetailsBlock::Markdown will turn into DetailsBlock::Html later.)