Skip to content

Consecutive occurences of examples lead to empty DetailsBlocks in docs.json #7323

@YDX-2147483647

Description

@YDX-2147483647

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:

/// 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:

typst/docs/src/lib.rs

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    docsImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions