feat(html): cache bust static files by adding hashes to file names

Closes #1254

Author: notriddle

Cargo.lock

@@ -27,13 +27,15 @@ clap_complete = "4.3.2"
 once_cell = "1.17.1"
 env_logger = "0.11.1"
 handlebars = "6.0"
+hex = "0.4"
 log = "0.4.17"
 memchr = "2.5.0"
 opener = "0.7.0"
 pulldown-cmark = { version = "0.10.0", default-features = false, features = ["html"] } # Do not update, part of the public api.
 regex = "1.8.1"
 serde = { version = "1.0.163", features = ["derive"] }
 serde_json = "1.0.96"
+sha2 = "0.9"
 shlex = "1.3.0"
 tempfile = "3.4.0"
 toml = "0.5.11" # Do not update, see https://github.com/rust-lang/mdBook/issues/2037

Cargo.toml

@@ -13,6 +13,7 @@ mathjax-support = true
 site-url = "/mdBook/"
 git-repository-url = "https://github.com/rust-lang/mdBook/tree/master/guide"
 edit-url-template = "https://github.com/rust-lang/mdBook/edit/master/guide/{path}"
+hash-files = true
 
 [output.html.playground]
 editable = true

guide/book.toml

@@ -168,6 +168,11 @@ The following configuration options are available:
   This string will be written to a file named CNAME in the root of your site, as
   required by GitHub Pages (see [*Managing a custom domain for your GitHub Pages
   site*][custom domain]).
+- **hash-files:** Include a cryptographic "fingerprint" of the files' contents in CSS, JavaScript, and image asset filenames,
+  so that if the contents of the file are changed, the name of the file will also change.
+  For example, `css/chrome.css` may become `css/chrome-9b8f428e.css`.
+  HTML files are not renamed.
+  Static CSS and JS files can reference each other using `{{ resource "filename" }}` directives.
 
 [custom domain]: https://docs.github.com/en/github/working-with-github-pages/managing-a-custom-domain-for-your-github-pages-site
 

guide/src/format/configuration/renderers.md

@@ -99,3 +99,13 @@ Of course the inner html can be changed to your liking.
 
 *If you would like other properties or helpers exposed, please [create a new
 issue](https://github.com/rust-lang/mdBook/issues)*
+
+### 3. resource
+
+The path to a static file.
+It implicitly includes `path_to_root`,
+and accounts for files that are renamed with a hash in their filename.
+
+```handlebars
+<link rel="stylesheet" href="{{ resource "css/chrome.css" }}">
+```

guide/src/format/theme/index-hbs.md

@@ -587,6 +587,9 @@ pub struct HtmlConfig {
     /// The mapping from old pages to new pages/URLs to use when generating
     /// redirects.
     pub redirect: HashMap<String, String>,
+    /// If this option is turned on, "cache bust" static files by adding
+    /// hashes to their file names.
+    pub hash_files: bool,
 }
 
 impl Default for HtmlConfig {
@@ -616,6 +619,7 @@ impl Default for HtmlConfig {
             cname: None,
             live_reload_endpoint: None,
             redirect: HashMap::new(),
+            hash_files: false,
         }
     }
 }