# RustDoc using layout/skin from MDN JavaScript docs **URL:** \ **Category:** tools and infrastructure\ **Created:** [February 2, 2023, 9:48pm UTC](https://internals.rust-lang.org/t/rustdoc-using-layout-skin-from-mdn-javascript-docs/18262 "2023-02-02T21:48:05Z")\ **Posts on this page:** 11\ **Page:** 1
**Author:** ![hydroper1](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/hydroper1/32/12099_2.png) [@hydroper1](https://internals.rust-lang.org/u/hydroper1)\ **Post date:** [February 2, 2023, 9:48pm UTC](https://internals.rust-lang.org/t/rustdoc-using-layout-skin-from-mdn-javascript-docs/18262/1 "2023-02-02T21:48:05Z")
I personally find MDN docs skinning more enjoyable than RustDoc. I've said something similiar about JavaDoc too, as well. Anyone feels something similiar? I think it needs to change. Currently I can't achieve anything because RustDoc only allows to customize CSS. For comparison: - An example of RustDoc: [`ffmpeg_next::Chapter`](https://docs.rs/ffmpeg-next/5.1.1/ffmpeg_next/struct.Chapter.html) - An example of JavaScript MDN docs: [`RegExp`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp) P.S.: regarding user experience, RustDoc is pretty well-accessible. I'm just pointing that I don't find it visually pleasant. ---
**Author:** ![CAD97](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/cad97/32/3460_2.png) [@CAD97](https://internals.rust-lang.org/u/CAD97)\ **Post date:** [February 3, 2023, 12:33am UTC](https://internals.rust-lang.org/t/rustdoc-using-layout-skin-from-mdn-javascript-docs/18262/2 "2023-02-03T00:33:38Z")
Interestingly, at least in the part of the Rust world I'm exposed to on Twitter, most people weren't very fond of the early 2022 MDN redesign. - Feb 2022: [https://web.archive.org/web/20220228182617/https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global\_Objects/RegExp](https://web.archive.org/web/20220228182617/https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp) - March 2022: [https://web.archive.org/web/20220301190408/https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global\_Objects/RegExp](https://web.archive.org/web/20220301190408/https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp) Rustdoc offers [a JSON output of its collected data](https://rust-lang.github.io/rfcs/2963-rustdoc-json.html). If you want an alternative frontend, rendering from that is going to be the way forward. Structurally different frontend skins essentially aren't going to ever be supported by Rustdoc. Rustdoc has the interesting constraint of needing to be an entirely static site browsable straight off of the filesystem and not requiring any JavaScript to view the content of the page. Additionally, the team's already mildly concerned with the size of the rendered documentation bundle's size, and as such large increases to bundle size typically aren't accepted, especially if they wouldn't have any tangible benefit to the average stable user. In general, the team agrees that Rustdoc isn't a great solution of exploratory discovery of an API's functionality. However, improvements to Rustdoc's use as such aren't typically going to be accepted if they regress the primary goal of Rustdoc as reference documentation, or the secondary properties of static bundle size and JS-independence. ---
**Author:** ![hydroper1](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/hydroper1/32/12099_2.png) [@hydroper1](https://internals.rust-lang.org/u/hydroper1)\ **Post date:** [February 8, 2023, 6:29pm UTC](https://internals.rust-lang.org/t/rustdoc-using-layout-skin-from-mdn-javascript-docs/18262/3 "2023-02-08T18:29:16Z")
> [@CAD97](#): > > Rustdoc has the interesting constraint of needing to be an entirely static site browsable straight off of the filesystem and not requiring any JavaScript to view the content of the page. Oh, but I mean, that constraint won't be broken by changing the "skin" of the generated docs. It's just skin; functionality such as portability remains the same. > [@CAD97](#): > > In general, the team agrees that Rustdoc isn't a great solution of exploratory discovery of an API's functionality. Are you sure they think so? Sometimes you just don't want to open an IDE and want to explore what a crate looks like before downloading it. ---
**Author:** ![CAD97](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/cad97/32/3460_2.png) [@CAD97](https://internals.rust-lang.org/u/CAD97)\ **Post date:** [February 8, 2023, 11:40pm UTC](https://internals.rust-lang.org/t/rustdoc-using-layout-skin-from-mdn-javascript-docs/18262/4 "2023-02-08T23:40:45Z")
> [@hydroper1](#): > > It's just skin; The problem is that while the information presented does stay the same, the structure of the presentation does change, and that's somewhere between very difficult and impossible to do with just switching out CSS. As much as semantic HTML is an ideal, HTML is a document language, and it describes the structure of the document, not the structure of the data. If you change the structure of the document, the HTML usually has to change to reflect that. > [@hydroper1](#): > > Are you sure they think so? I'm not saying that they don't care about rustdoc usage as exploratory documentation, just that it's not _the_ primary (but is still _a_) priority of the docs. What I'm trying to say there is that they know that it's suboptimal and would like to improve its functionality in that domain, just not at the (perceived?) expense of another priority of the system. ---
**Author:** ![hydroper1](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/hydroper1/32/12099_2.png) [@hydroper1](https://internals.rust-lang.org/u/hydroper1)\ **Post date:** [February 9, 2023, 12:37pm UTC](https://internals.rust-lang.org/t/rustdoc-using-layout-skin-from-mdn-javascript-docs/18262/5 "2023-02-09T12:37:44Z")
> [@CAD97](#): > > the structure of the presentation does change No need for reflecting changes in all existing docs in docs.rs. Just apply the new skin to future docs.rs docs. ---
**Author:** ![jer](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/jer/32/1009_2.png) [@jer](https://internals.rust-lang.org/u/jer)\ **Post date:** [February 9, 2023, 2:24pm UTC](https://internals.rust-lang.org/t/rustdoc-using-layout-skin-from-mdn-javascript-docs/18262/6 "2023-02-09T14:24:47Z")
So ... just dropping the current theme? Yeah, that's not going to happen. @CAD97 already laid out some arguments and gave you information so you can work on alternative frontends: use the generated JSON. ---
**Author:** ![hydroper1](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/hydroper1/32/12099_2.png) [@hydroper1](https://internals.rust-lang.org/u/hydroper1)\ **Post date:** [February 9, 2023, 2:29pm UTC](https://internals.rust-lang.org/t/rustdoc-using-layout-skin-from-mdn-javascript-docs/18262/7 "2023-02-09T14:29:37Z")
> [@jer](#): > > So ... just dropping the current theme? Yeah, that's not going to happen. Any more argument to that? > [@jer](#): > > @CAD97 already laid out some arguments and gave you information so you can work on alternative frontends: use the generated JSON. I'd prefer to have the different-skin docs in docs.rs than a custom place somewhere else. ---
**Author:** ![jer](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/jer/32/1009_2.png) [@jer](https://internals.rust-lang.org/u/jer)\ **Post date:** [February 9, 2023, 2:34pm UTC](https://internals.rust-lang.org/t/rustdoc-using-layout-skin-from-mdn-javascript-docs/18262/8 "2023-02-09T14:34:34Z")
> [@hydroper1](#): > > Any more argument to that? It works, it exists, it's familiar and some people seem to be okay with it. Introducing a large change as what you propose here has a cost. So far you haven't made a case that changing the theme and all the work it requires is worth the effort. "I don't like that theme" is not good enough of a reason. > [@hydroper1](#): > > I'd prefer to have the different-skin docs in docs.rs than a custom place somewhere else. You might. Others might want something different. If you want to convince people that rustdoc should provide a different theme you will have to make an effort to convince people that it's worth it. That might mean experimenting on your own, outside of the official places. I for one don't think a theme closer to what MDN looks like today works to transport the same information rustdoc has. ---
**Author:** ![hydroper1](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/hydroper1/32/12099_2.png) [@hydroper1](https://internals.rust-lang.org/u/hydroper1)\ **Post date:** [February 9, 2023, 2:50pm UTC](https://internals.rust-lang.org/t/rustdoc-using-layout-skin-from-mdn-javascript-docs/18262/9 "2023-02-09T14:50:04Z")
Yes, I didn't no effort or experiment so far. I just wanted to know if it'd be feasible for them to apply changes on future docs.rs docs. > [@jer](#): > > I for one don't think a theme closer to what MDN looks like today works to transport the same information rustdoc has. It doesn't need to match exactly MDN at all though. ---
**Author:** ![jer](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/jer/32/1009_2.png) [@jer](https://internals.rust-lang.org/u/jer)\ **Post date:** [February 9, 2023, 3:02pm UTC](https://internals.rust-lang.org/t/rustdoc-using-layout-skin-from-mdn-javascript-docs/18262/10 "2023-02-09T15:02:55Z")
> [@hydroper1](#): > > Yes, I didn't no effort or experiment so far. I just wanted to know if it'd be feasible for them to apply changes on future docs.rs docs. Small, iterative changes? Sure. Major changes that will require changing the complete layout? Very unlikely. ---
**Author:** ![system](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/system/32/14092_2.png) [@system](https://internals.rust-lang.org/u/system)\ **Post date:** [May 10, 2023, 3:03pm UTC](https://internals.rust-lang.org/t/rustdoc-using-layout-skin-from-mdn-javascript-docs/18262/11 "2023-05-10T15:03:33Z")
This topic was automatically closed 90 days after the last reply. New replies are no longer allowed.