rust-lang / rust-lang/mdBook

Add preload CSS/JS support

Open
#2,957 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

C-enhancement
Dominant language
Rust
Stars
22.2k
Forks
1.9k
PR merge metrics
PR metrics pending

Description

Problem

Due to HTTP pipelining, content of a web page can be loaded/rendered before subsequent CSS files have been loaded. The end result is a semi-rendered page that "shifts" or "shimmers" once the CSS finishes loading / other CSS file fetches are completed. The same can apply to JavaScript.

HTML <link rel="preload"> solves this problem and is well-supported in all major browesrs (going back many, many versions). Reading Speculative loading may also provide additional benefits. (Note: do not mix up "preload" and "prefetch"! They are very different; in general "prefetch" is not needed these days.)

mdBook currently does not support a way to use preloading, which will result in the aforementioned behaviour.

Proposed Solution

Offer a way via TOML config to enable HTML link preloading. A default value of false (disabled) would be perfectly reasonable (i.e. retain existing behaviour).

Notes

No response

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by locating mdBook's TOML configuration handling and the HTML generation entry points; the issue does not name specific files or tests. Determine how a configuration option should control HTML link preloading, then verify that the default remains disabled and generated pages include preload links only when enabled.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
documentation, web-dev
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.