Merge pull request #1311 from dtolnay/cname

Support emitting CNAME file for publishing at a custom domain

Author: ehuss

book-example/src/format/config.md

@@ -210,6 +210,12 @@ The following configuration options are available:
 - **site-url:** The url where the book will be hosted. This is required to ensure
   navigation links and script/css imports in the 404 file work correctly, even when accessing
   urls in subdirectories. Defaults to `/`.
+- **cname:** The DNS subdomain or apex domain at which your book will be hosted.
+  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]).
+
+[custom domain]: https://docs.github.com/en/github/working-with-github-pages/managing-a-custom-domain-for-your-github-pages-site
 
 Available configuration options for the `[output.html.fold]` table:
 
@@ -273,6 +279,7 @@ no-section-label = false
 git-repository-url = "https://github.com/rust-lang/mdBook"
 git-repository-icon = "fa-github"
 site-url = "/example-book/"
+cname = "myproject.rs"
 input-404 = "not-found.md"
 
 [output.html.fold]

src/config.rs

@@ -508,6 +508,13 @@ pub struct HtmlConfig {
     pub input_404: Option<String>,
     /// Absolute url to site, used to emit correct paths for the 404 page, which might be accessed in a deeply nested directory
     pub site_url: Option<String>,
+    /// The DNS subdomain or apex domain at which your book will be hosted. 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]).
+    ///
+    /// [custom domain]: https://docs.github.com/en/github/working-with-github-pages/managing-a-custom-domain-for-your-github-pages-site
+    pub cname: Option<String>,
     /// This is used as a bit of a workaround for the `mdbook serve` command.
     /// Basically, because you set the websocket port from the command line, the
     /// `mdbook serve` command needs a way to let the HTML renderer know where
@@ -541,6 +548,7 @@ impl Default for HtmlConfig {
             git_repository_icon: None,
             input_404: None,
             site_url: None,
+            cname: None,
             livereload_url: None,
             redirect: HashMap::new(),
         }

src/renderer/html_handlebars/hbs_renderer.rs

@@ -187,6 +187,10 @@ impl HtmlHandlebars {
             b"This file makes sure that Github Pages doesn't process mdBook's output.",
         )?;
 
+        if let Some(cname) = &html_config.cname {
+            write_file(destination, "CNAME", format!("{}\n", cname).as_bytes())?;
+        }
+
         write_file(destination, "book.js", &theme.js)?;
         write_file(destination, "css/general.css", &theme.general_css)?;
         write_file(destination, "css/chrome.css", &theme.chrome_css)?;