rust-lang / rust-lang/mdBook

Definition list are broken with several definitions and block elements

Open Beginner friendly
#3,220 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

C-bug
Dominant language
Rust
Stars
22.2k
Forks
1.9k
PR merge metrics
PR metrics pending

Description

Hello,

Problem

When adding block elements (<ul>, <blockquote>, <dl>...) in a definition (<dd>) the render is good, unless having several definitions

# Example

Single definition
  : a definition with some block elements

    > This is a blockquote

    * This is an item of unordered list
    * Another item

    Nested definition term
      : foo
      : bar

Several definitions
  : the same definition as above list with some block elements

    > This is a blockquote

    * This is an item of unordered list
    * Another item

    Nested definition term
      : foo
      : bar

  : but with another definition

Several definitions "fixed" with a `<div>`
  : <div>the same definition as above list with some block elements wrapped in a <code>&lt;div&gt;</code>

    > This is a blockquote

    * This is an item of unordered list
    * Another item

    Nested definition term
      : foo
      : bar

    </div>

  : but with another definition

Image
Steps
  1. use a definition list
  2. add block elements in the definition
  3. add another definitions
Possible Solution(s)

It is caused by this display: flex

https://github.com/rust-lang/mdBook/blob/6a75867463828eb5b0b00f78feb0224c1bbc39aa/crates/mdbook-html/front-end/css/general.css#L314

  • maybe the CSS can be changed (i think, it's preferable)
  • maybe a <div> can wrap the content of the <dd>
Notes

Also, i would recommend wrapping definitions (<dl> + <dd>) in <div>, it is easier to add custom style

<dl>
	<div>
		<dt>Term 1</dt>
		<dd>Definition</dd>
	</div>
	<div>
		<dt>Term 2</dt>
		<dd>Definition 1</dd>
		<dd>Definition 2</dd>
	</div>
</dl>

https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/dl#wrapping_name-value_groups_in_div_elements

Version
0.5.4

And the current main branch

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with crates/mdbook-html/front-end/css/general.css at the linked display:flex rule, then reproduce the Markdown example from the issue in mdBook. Compare single and multiple definitions containing block elements; done means both render correctly without requiring the workaround described in the issue.

Written by the indexing model from the issue text.

Assessment

Tech stack
css, html
Domain
frontend
Issue type
Bug
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
72/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.