Feature request: inject syntax highlighting for TOML into crate docs
abonander opened this issue · 5 comments
I just ran into this while working on launchbadge/sqlx#3383
It'd be really nice to have syntax highlighting for TOML in crate docs, because I'm including a lot of it.
I found #1047 which was closed already and the upstream issue rust-lang/rust#43165, but the general disposition for the latter seems to be summed up by this comment: rust-lang/rust#43165 (comment)
It doesn't seem likely that rustdoc itself will gain support for this anytime soon.
The reason I'm opening this issue is because this comment points out that TOML syntax highlighting is already available on the details pages for crates. It doesn't seem like it would take much to inject it into the HTML for the docs themselves.
btw, thanks for your library, I'm currently in the process of migrating docs.rs to it :)
The reason I'm opening this issue is because rust-lang/rust#43165 (comment) points out that TOML syntax highlighting is already available on the details pages for crates. It doesn't seem like it would take much to inject it into the HTML for the docs themselves.
We have some pages where we actually do highlighting, there are:
- the mentioned crate detail page ( = the markdown readme): https://docs.rs/crate/sqlx/latest
- our own source pages (where just show the crate sources): https://docs.rs/crate/sqlx/latest/source/Cargo.toml
in both cases we have the actual source and render a highlighted HTML version using comrak.
Now back to your topic. Docs.rs just runs a (relatively) normal cargo doc command and stores the final HTML.
So to add highlighting to these documentation pages we would have to parse the old HTML, find code blocks, and rewrite these with a highlighted version, and all taking into account the styling outside of the code block.
So while we actually could rewrite HTML (we are already rewriting small parts, for example to add the top / bottom bar), the actual correct place would be rustdoc, since then users using docs.rs would see the same docs as users running the doc build locally. Also I believe a well readable doc page without broken styling, across all nightly rustdoc versions would be really hard.
of course we could also use frontend techniques to do something similar, but with similar issues keeping it stable across versions
I think we should just add highlightjs at this point and run it by default on all pages.
I think we should just add highlightjs at this point and run it by default on all pages.
you mean that rustdoc should do this ? or docs.rs?
I don't have much experience with highlight.js, I only know that for the pages we render ourselves (like our source) it was replaced by server side highlighting.
Wouldn't this conflict with the cases where rustdoc is already highlighting, like its own source pages?
I meant docs.rs. And I can write the JS so highlightjs only takes a look at not highlighted code examples.