melissawm / sphinx-tags

A tiny Sphinx extension that implements blog-style tags for documentation.
https://sphinx-tags.readthedocs.io/en/latest/
MIT License
44 stars 11 forks source link

Normalize tag URLs #56

Closed JWCook closed 10 months ago

JWCook commented 1 year ago

Here's an idea for a small cosmetic improvement (related to #39): Make tag URLs with whitespace or other non-alphanumeric characters more easily human-readable. This could be done by normalizing them the same way Markdown normalizes heading anchor links.

Markdown anchors

For example, if you have a Markdown heading like:

# Title: subtitle (parenthetical)

The anchor link generated for that will look like:

page.html#title-subtitle-parenthetical

Instead of:

page.html#title%3A%20subtitle%20%28parenthetical%29

I can't find the exact rules in the Commonmark spec, but it looks like it just replaces spaces with hyphens, and strips out any other special characters. I am guessing it does this mainly to make it a valid HTML attribute (<a id="...">), but has the side effect of making a more readable link.

Tag URLs

We could do the same for tag URLs, so they always appear without any urlencoded characters, like:

https://site.com/tags/normalized-tag-label.html

I could submit a PR for that if you'd like.

melissawm commented 1 year ago

I like that, feel free to do it 🚀