Repository navigation
rustdoc trims all digits except the last two in an ordered list #161144
Description
Activity
I can supply the actual files under
./doc/if needed. What gets rendered on the top-level crate HTML looks something like:Structs
B
Enums
A A.
Notice the lack of summary doc next to
BunlikeA. When on the page forB, it looks like:pub struct B;Notice that it shows "23" not "123".
On the page for
A, it looks like:pub enum A { B, }A.
Variants
B
23.Again, notice the comment for variant
Bsays "23" instead of "123".When a period is removed, the "1" is not trimmed.
- changed the title
[-]`rustdoc` incorrectly trims integers[/-][+]`rustdoc` incorrectly trims integers with a period at the end[/+]on Aug 15, 2026 While I haven't bothered testing all versions of
rustdoc, I believe this is a regression introduced in1.57.0since the "1" doesn't get trimmed using1.56.1. I tried a handful more between1.57.0and1.97.1, and all of them trim the "1".- changed the title
[-]`rustdoc` incorrectly trims integers with a period at the end[/-][+]`rustdoc` trims all digits except that last two when followed by a period[/+]on Aug 15, 2026 https://spec.commonmark.org/0.31.2/#ordered-list-marker:
An ordered list marker is a sequence of 1–9 arabic digits (0-9), followed by either a . character or a ) character.
- added and removed
on Aug 17, 2026 As @Urgau underlined, it's as expected, following the markdown spec. I think there is nothing for us to do here.
While this doesn't matter for my specific case since the solution is for me to escape the period, why is
rustdocnot displaying the entire value? The HTML does have it as an ordered list with"start"set to the correct value, but the CSS or something else is causing it to not be rendered correctly.As stated above,
1.56.1renders it correctly.Another example:
//! Ordered list starting at 123 per the spec: //! //! 123. Apple. //! 124. Orange.
This should be rendered as:
Ordered list starting at 123 per the spec:
- Apple.
- Orange.
But
rustdoc, despite generating the correct HTML as something like:<p>Ordered list starting at 123 per the spec:</p> <ol start="123"> <li>Apple.</li> <li>Orange.</li> </ol>
doesn't actually render the item numbers correctly since it trims all but the last two digits. What gets rendered looks like:
Ordered list starting at 123 per the spec:
- Apple.
- Orange.
- changed the title
[-]`rustdoc` trims all digits except that last two when followed by a period[/-][+]`rustdoc` trims all digits except the last two in an ordered list[/+]on Aug 17, 2026 That's a fair point. I suspect a change in
pulldown-cmarkmight be the reason. Do you have some extra context here @notriddle ?If it’s generating the correct HTML, then it’s not pulldown-cmark. It might be the CSS?
I can try bisecting
1.57.0to see what changes occurred from1.56.1since as stated the rendering is correct for that version; while1.57.0,1.60.0,1.70.0,1.80.0,1.90.0,1.97.1/stable, andnightlyall render the list incorrectly which makes me believe that all versions since1.57.0inclusive have this likely-CSS bug.Only removing
<link rel="stylesheet" href="../static.files/rustdoc-17e0aaed.css">from the HTML correctly renders all the digits.
Only removing<div class="docblock">and its associated end tag correctly renders all the digits.Well my first foray with all this AI/LLM stuff proved successful I believe. According to Claude, this is the problem:
Found it. The culprit is this rule from the CSS file:
.docblock>:not(.more-examples-toggle):not(.example-wrap){max-width:100%;overflow-x:auto;}
Your
<ol start="123">is a direct child of.docblock, so it matches and getsoverflow-x:auto.Here's the chain of events:
ol,ul{padding-left:24px;}reserves only 24px for markers — enough for a couple digits, not three.- List markers are
list-style-position: outsideby default, so they render in that 24px padding area, to the left of the content box. - Normally an overflowing outside marker is harmless — it just spills into the margin, unclipped.
- But once you set
overflow-x:autoon the list itself (as this rule does), the browser establishes a scroll/clip container. Now that overflowing marker gets clipped at the edge of the scrollport instead of spilling freely — and since the scroll position starts at the left, the leading digits (the ones sticking furthest left) get cut off, leaving just the trailing digits like "23." instead of "123.".
Fix: exclude lists from that overflow rule, e.g.:
.docblock>:not(.more-examples-toggle):not(.example-wrap):not(ol):not(ul){max-width:100%;overflow-x:auto;}
or simply add
overflow-x:visibleback forol/ulinside.docblock, or switch tolist-style-position:insideso markers sit inside the padded box instead of overflowing it.Following its advice about excluding lists from the overflow rule in rustdoc-17e0aaed.css renders the item numbers correctly.
Note I'm not a CSS expert, so the above could very well be wrong. I know how "triggering" AI/LLM use can be, so I apologize if I broke any guidelines with its use. Feel free to hide this comment if it's harmful. I also realize that there is still work to do in terms of fixing the actual code that generated this CSS file.
It's okay, but we're going to need to decide what to do about this, because that rule, when it was introduced in #88742, fixed a different layout bug.
I would think the solution would be to partially revert that PR, except on tables and code blocks, and add the z-index to the sidebar. That way, we don't need to worry about weird scrolling behavior on unexpected elements.
The alternative is to make the list elements' padding bigger, so that numbered lists can grow into the triple digits without anything breaking.
Seems like you already have a plan in mind. Gonna assign the issue to you then.
- The alternative is to make the list elements' padding bigger, so that numbered lists can grow into the triple digits without anything breaking.I don’t like that alternative since it’s overly specific to this example. Ordered list numbers can start at any value so long as the starting value isn’t more than 9 digits long; thus if anything, you should let numbered lists grow into 9 digits. I think the partial revert is more appropriate. Note the actual doc I had was for 4-digit years. Granted, I don’t want it to be interpreted as a list; so I’m now escaping the period but still.
- added a commit that references this issue
on Aug 21, 2026
I tried this code:
I expected to see this happen:
rustdoc src/lib.rsto generate docs with the correct comments.Instead, this happened:
rustdoc src/lib.rsgenerates documentation trimming 1. Additionally it doesn't generate any summary docs forBin themod.Meta
rustc --version --verbose: