Start using mdbook-spec for the reference.

This preprocessor adds support for several Markdown extensions that
should assist with writing.

Author: ehuss

README.md

@@ -12,6 +12,7 @@ what we have for now.
 
 - Nightly Rust
 - [mdbook](https://rust-lang.github.io/mdBook/)
+- [`mdbook-spec`](https://github.com/rust-lang/spec/tree/main/mdbook-spec)
 
 ## Installing dependencies
 
@@ -29,6 +30,12 @@ build the Reference:
 cargo install --locked mdbook
 ```
 
+Also install `mdbook-spec` which is a preprocessor which adds some Markdown extensions:
+
+```sh
+cargo install --locked mdbook-spec
+```
+
 ## Building
 
 To build the Reference, first clone the project:

book.toml

@@ -15,3 +15,5 @@ edit-url-template = "https://github.com/rust-lang/reference/edit/master/{path}"
 
 [rust]
 edition = "2021"
+
+[preprocessor.spec]

theme/reference.css

@@ -1,3 +1,5 @@
+/* Custom CSS for the Rust Specification. */
+
 /*
 .parenthetical class used to keep e.g. "less-than symbol (<)" from wrapping
 the end parenthesis onto its own line. Use in a span between the last word and
@@ -51,3 +53,167 @@ main .warning p::before {
 .ayu main .warning p a {
     color: #80d0d0;
 }
+
+/* <kbd> tags can be used to highlight specific character elements. */
+kbd {
+    border: 1px solid #999;
+    display: inline-block;
+    border-radius: 3px;
+    padding: 0 0.6ex;
+    background: #eee;
+    box-shadow: inset -1px -1px 0 #999;
+    vertical-align: baseline;
+    color: #000;
+    height: 1.55em;
+    font-style: normal;
+    font-weight: bold;
+    font-family: inherit;
+    font-size: revert;
+    line-height: revert;
+}
+kbd.optional {
+    border-style: dashed;
+    background: #fff;
+}
+var.optional {
+    border-style: dashed;
+}
+
+/* <var> tags can be used for non-terminals. */
+var {
+    border: 1px solid #9c9;
+    box-shadow: inset -1px -1px 0 #9c9;
+    font-style: normal;
+    display: inline-block;
+    vertical-align: baseline;
+    border-radius: 7px;
+    padding: 0 4px;
+    background: #dfd;
+    margin: 2px;
+}
+var.type {
+    box-shadow: inset -1px -1px 0 #c99;
+    border-color: #c99;
+    background: #fdd;
+}
+
+/* <span class="repeat"> can be used for a grammar production that repeats zero or more times. */
+span.repeat {
+    position: relative;
+    border: 1px dashed #393;
+    border-radius: 10px;
+    display: inline-block;
+    padding: 6px;
+    margin-left: 0.5ex;
+    margin-top: 1em;
+    margin-bottom: 0.5ex;
+    min-width: 3.8em;
+    text-align: center;
+}
+span.repeat::before {
+    content: "zero or more";
+    white-space: nowrap;
+    display: block;
+    text-align: center;
+    font-size: 0.75em;
+    position: absolute;
+    left: 0;
+    right: 0;
+    top: -1.4em;
+    color: #393;
+}
+var > span {
+    display: inline-block;
+    border-right: 1px dotted green;
+    padding-right: 0.5ex;
+    margin-right: 0.5ex;
+    font-style: italic;
+}
+
+/* <span class="version"> can be used to highlight a specific version of Rust. */
+span.version {
+    float: right;
+    margin-left: 1em;
+    margin-bottom: 1em;
+    background: #f7c0eb;
+    padding: 0.2ex 0.5ex;
+    border-radius: 5px;
+    display: block;
+    box-shadow: inset -1px -1px 0 #a06894;
+    font-size: 0.9em;
+}
+
+/* <dfn> tags are used to indicate a specific word or phrase is being defined. */
+dfn {
+    font-style: italic;
+    text-decoration: underline;
+}
+
+.content main {
+    /* Provides space on the left for the rule call-outs. */
+    padding-left: 4em;
+}
+
+/* Rules are generated via r[foo.bar] syntax, processed by mdbook-spec. */
+.rule {
+    /* Allows the rule to be positioned. */
+    position: relative;
+    /* Position slightly to the left. */
+    left: -4em;
+    color: #999;
+    font-size: 0.8em;
+}
+/* mdbook will wrap the rule content in a <p> tag, with a margin. However, we
+   don't need the extra space
+*/
+.rule ~ p {
+    margin-top: 0px;
+}
+
+/* Change the default styling of blockquotes. */
+blockquote {
+    padding: 1ex 1em;
+    margin: 1ex;
+    margin-left: 2em;
+    /* vw units allow this to be adaptive to the screen size so it isn't too small on mobile. */
+    margin-right: 12vw;
+}
+
+/* mdbook will wrap the blockquote content in a <p> tag, with a margin. However,
+   that adds too much space, so remove it.
+*/
+blockquote > p {
+    margin-top: 0px;
+    margin-bottom: 0px;
+}
+
+/* When the sidebar is visible, reduce the spacing of rules so that the
+   content doesn't get shifted too far, and make the text too narrow.
+*/
+.sidebar-visible .rule {
+    left: -1em;
+}
+.sidebar-visible .content main {
+    padding-left: 1em;
+}
+
+/* Remove the blue coloring of links on rules that mdbook normally sets. */
+.rule-link {
+    color: #999 !important;
+}
+
+/* When clicking a rule, it is added as a URL fragment and the browser will
+   navigate to it. This adds an indicator that the linked rule is the one that
+   is "current", just like normal headers are in mdbook.
+*/
+.rule:target::before {
+    display: inline-block;
+    content: "»";
+    margin-inline-start: -20px;
+    width: 20px;
+}
+
+/* Sets the color for [!HISTORY] blockquote admonitions. */
+.history > blockquote {
+    background: #f7c0eb;
+}