Join GitHub today
GitHub is home to over 20 million developers working together to host and review code, manage projects, and build software together.
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
Already on GitHub? Sign in to your account
Dev Docs (Formatting Only): Convert Fake Subheadings To Real Subheadings #661
Conversation
saivann
commented on an outdated diff
Nov 29, 2014
| +check-for-duplicate-header-ids: | ||
| +## When Kramdown automatically creates header id tags, it avoids using | ||
| +## the same id="" as a previous header by silently appending '-1' to the | ||
| +## second-occuring header. We want an error when this happens because | ||
| +## all links which previously pointed to the second-occuring header now | ||
| +## point to the first-occuring header. (Example: before this test was | ||
| +## written, links pointing to the ping RPC were silently redirected when | ||
| +## the P2P ping message was added to the page.) The pattern below will | ||
| +## report a false positive if we legitimately have an id ending in '-1', | ||
| +## but that should be easy to work around if it ever happens. | ||
| + $S grep '<h[1-6][^>]\+id="[^"]\+-1"' _site/en/developer-* | eval $(ERROR_ON_OUTPUT) | ||
| + | ||
| +check-for-headers-with-hrefs: | ||
| +## Subheadings with Kramdown-generated id tags break anchor link | ||
| +## affordance if their text includes any links (hrefs), so error if any | ||
| +## links are detectd between <h[2-6]> and </h[2-6> header tags. If we |
saivann
Contributor
|
|
@harding That makes sense, I didn't think about those issues! I have just sent you two pull requests. One to allow headers with hrefs directly so we don't need to test against it and another to update the toc correctly as you suggested. |
harding
added some commits
Nov 29, 2014
|
@saivann Merged your pulls, tested, and added back in a heavily revised form of the removed Makefile test which tests for only the specific issue I had---autocrossref messing up headers. I also updated the previews. Thank you so much for your help! In the absence of critical feedback, I'll merge this request around 02:00 UTC Sunday. |
|
@harding LGTM, thanks! |
harding commentedNov 29, 2014
We currently use fake subheadings in a few places where we don't want to add entries to the table of contents (TOC). The fake subheadings are simply short paragraphs where all text is bold:
An Example Fake Subheading
Real headings would be nicer as they're automatically given an anchor and a clickable link when you hover over them, just like GitHub does on README files.
It turns out we can do that quite easily. Kramdown lets you create real subheadings which won't be included in the table of contents by putting
{:.no_toc}on the line after the subheading definition. It's a built-in feature, so there's no special plugin or Javascript required. (Yay!) http://kramdown.gettalong.org/converter/html.html#tocThis pull converts all the non-RPC fake subheadings to real-non-TOC subheadings (I don't think the RPC fake subheadings need anchor links, so I didn't do them.)
[This part edited to remove warning that this pull was incomplete. It's complete now thanks to @saivann]
This pull also fixes a semi-broken link and adds two Makefile tests to detect that and similar broken links in the future.
I've tested that this pull neither adds nor removes nor changes anything in the table of contents (except for the collapse issue). Here are links to the new real subheadings---notice that they don't appear in the TOC (when the TOC is displayed):