add per-section numbering#602
Conversation
bhosmer-ant
force-pushed
the
basil/local_numbering
branch
from
046b088 to
3f79060
Compare
bhosmer-ant
force-pushed
the
basil/local_numbering
branch
from
3f79060 to
73b42f6
Compare
bhosmer-ant
force-pushed
the
basil/local_numbering
branch
from
73b42f6 to
1f5ebd8
Compare
jonathanhefner
left a comment
jonathanhefner
left a comment
There was a problem hiding this comment.
There is a neat way to do this with just CSS:
h1 {
counter-reset: h2-counter;
}
h2 {
counter-reset: h3-counter;
}
h3 {
counter-reset: h4-counter;
}
h2::before {
counter-increment: h2-counter;
content: counter(h2-counter) ". ";
}
h3::before {
counter-increment: h3-counter;
content: counter(h2-counter) "." counter(h3-counter) " ";
}
h4::before {
counter-increment: h4-counter;
content: counter(h2-counter) "." counter(h3-counter) "." counter(h4-counter) " ";
}That way we won't have to worry about keeping the section numbers in sync with each other.
|
@bhosmer-ant If you would like, I can submit a PR that adds the above CSS, and removes the existing numbers from headings in other |
|
@jonathanhefner I appreciate it, but I'm a bit worried about delegating control of the numbering to CSS - I'm imagining future changes where we'd want numbering to deviate from the strict numbering scheme due to e.g. edits. (Also, I'm not sure how links could include section numbers if we went this route?) |
I'm unclear on what you mean. Do you mean that we would want to skip section numbers? Or that we would want sections to appear out of order (for example, section 2.2 appear before 2.1)?
Are you referring to the table of contents links on the right side of the page? We could apply similar CSS rules for those by targeting On the topic of links, though, it's worth mentioning that URLs for headings are automatically generated based on their text. For example, a heading that is hardcoded as "2.3 Authorization Server Discovery" will have a URL like https://modelcontextprotocol.io/specification/draft/basic/authorization#2-3-authorization-server-discovery. This means that if we change the number in the heading, any links to it will break. For example, this link: will break if we add a new section before 2.3 and update the 2.3 heading to match the new order. |
|
Replies below, but TLDR with the TOC issue addressed this seems pretty compelling in terms of future maintenance burden. If you wouldn't mind putting up a PR to try out that would be awesome, thank you!
Yeah, was thinking about what would happen if we wanted to "pin" section numbers in the future. I think more broadly I just have some FUD about coupling the canonical spec document so tightly to CSS. But maybe I'm overthinking it.
Ah ok - the TOC was the main thing. I was also thinking about deep links from outside wanting to carry section information, e.g. https://mcp-staging-basil-local_numbering.mintlify.app/specification/draft/server/tools#3-1-listing-tools, but of course this cuts both ways, since omitting section numbers from these would protect them from drift due to renumbering, per your next point.
True. And in fact I hadn't yet gone through and fixed existing internal links to include numbers. |
3 participants
Adds local numbering at the section level (Architecture, ...). staged