rustdoc: Add --highlight-foreign-code unstable flag

fasterthanlime · fasterthanlime · commit 89da8706ba28 · 2025-12-13T09:56:19.000+01:00
Gate the arborium-based syntax highlighting behind an unstable flag
(-Z unstable-options --highlight-foreign-code) so it can be tested
before becoming the default behavior.

The flag is threaded through:
- RenderOptions in config.rs
- SharedContext in context.rs
- Markdown/MarkdownWithToc structs in markdown.rs
- CodeBlocks iterator for actual highlighting
diff --git a/src/librustdoc/config.rs b/src/librustdoc/config.rs
@@ -312,6 +312,8 @@ pub(crate) struct RenderOptions {
     pub(crate) disable_minification: bool,
     /// If `true`, HTML source pages will generate the possibility to expand macros.
     pub(crate) generate_macro_expansion: bool,
+    /// If `true`, non-Rust code blocks will be syntax-highlighted using tree-sitter.
+    pub(crate) highlight_foreign_code: bool,
 }
 
 #[derive(Copy, Clone, Debug, PartialEq, Eq)]
@@ -805,6 +807,7 @@ impl Options {
         let no_capture = matches.opt_present("no-capture");
         let generate_link_to_definition = matches.opt_present("generate-link-to-definition");
         let generate_macro_expansion = matches.opt_present("generate-macro-expansion");
+        let highlight_foreign_code = matches.opt_present("highlight-foreign-code");
         let extern_html_root_takes_precedence =
             matches.opt_present("extern-html-root-takes-precedence");
         let html_no_source = matches.opt_present("html-no-source");
@@ -916,6 +919,7 @@ impl Options {
             include_parts_dir,
             parts_out_dir,
             disable_minification,
+            highlight_foreign_code,
         };
         Some((input, options, render_options, loaded_paths))
     }
diff --git a/src/librustdoc/externalfiles.rs b/src/librustdoc/externalfiles.rs
@@ -47,6 +47,7 @@ impl ExternalHtml {
                 edition,
                 playground,
                 heading_offset: HeadingOffset::H2,
+                highlight_foreign_code: false,
             }
             .write_into(&mut bc)
             .unwrap();
@@ -63,6 +64,7 @@ impl ExternalHtml {
                 edition,
                 playground,
                 heading_offset: HeadingOffset::H2,
+                highlight_foreign_code: false,
             }
             .write_into(&mut ac)
             .unwrap();
diff --git a/src/librustdoc/html/markdown.rs b/src/librustdoc/html/markdown.rs
@@ -20,6 +20,7 @@
 //!     edition: Edition::Edition2015,
 //!     playground: &None,
 //!     heading_offset: HeadingOffset::H2,
+//!     highlight_foreign_code: false,
 //! };
 //! let mut html = String::new();
 //! md.write_into(&mut html).unwrap();
@@ -99,6 +100,8 @@ pub struct Markdown<'a> {
     /// Offset at which we render headings.
     /// E.g. if `heading_offset: HeadingOffset::H2`, then `# something` renders an `<h2>`.
     pub heading_offset: HeadingOffset,
+    /// Whether to syntax-highlight non-Rust code blocks using tree-sitter.
+    pub highlight_foreign_code: bool,
 }
 /// A struct like `Markdown` that renders the markdown with a table of contents.
 pub(crate) struct MarkdownWithToc<'a> {
@@ -108,6 +111,7 @@ pub(crate) struct MarkdownWithToc<'a> {
     pub(crate) error_codes: ErrorCodes,
     pub(crate) edition: Edition,
     pub(crate) playground: &'a Option<Playground>,
+    pub(crate) highlight_foreign_code: bool,
 }
 /// A tuple struct like `Markdown` that renders the markdown escaping HTML tags
 /// and includes no paragraph tags.
@@ -210,6 +214,8 @@ struct CodeBlocks<'p, 'a, I: Iterator<Item = Event<'a>>> {
     // Information about the playground if a URL has been specified, containing an
     // optional crate name and the URL.
     playground: &'p Option<Playground>,
+    // Whether to use tree-sitter highlighting for non-Rust code blocks.
+    highlight_foreign_code: bool,
 }
 
 impl<'p, 'a, I: Iterator<Item = Event<'a>>> CodeBlocks<'p, 'a, I> {
@@ -218,8 +224,15 @@ impl<'p, 'a, I: Iterator<Item = Event<'a>>> CodeBlocks<'p, 'a, I> {
         error_codes: ErrorCodes,
         edition: Edition,
         playground: &'p Option<Playground>,
+        highlight_foreign_code: bool,
     ) -> Self {
-        CodeBlocks { inner: iter, check_error_codes: error_codes, edition, playground }
+        CodeBlocks {
+            inner: iter,
+            check_error_codes: error_codes,
+            edition,
+            playground,
+            highlight_foreign_code,
+        }
     }
 }
 
@@ -254,14 +267,17 @@ impl<'a, I: Iterator<Item = Event<'a>>> Iterator for CodeBlocks<'_, 'a, I> {
                         let lang_string = lang.map(|l| format!("language-{l}")).unwrap_or_default();
                         let whitespace = if added_classes.is_empty() { "" } else { " " };
 
-                        // Try to highlight with arborium if we have a language
-                        let code_html = lang
-                            .and_then(|l| {
+                        // Try to highlight with arborium if enabled and we have a language
+                        let code_html = if self.highlight_foreign_code {
+                            lang.and_then(|l| {
                                 highlight::highlight_foreign_code(l, original_text.trim_suffix('\n'))
                             })
                             .unwrap_or_else(|| {
                                 Escape(original_text.trim_suffix('\n')).to_string()
-                            });
+                            })
+                        } else {
+                            Escape(original_text.trim_suffix('\n')).to_string()
+                        };
 
                         return Some(Event::Html(
                             format!(
@@ -1354,6 +1370,7 @@ impl<'a> Markdown<'a> {
             edition,
             playground,
             heading_offset,
+            highlight_foreign_code,
         } = self;
 
         let replacer = move |broken_link: BrokenLink<'_>| {
@@ -1371,7 +1388,7 @@ impl<'a> Markdown<'a> {
             let p = SpannedLinkReplacer::new(p, links);
             let p = footnotes::Footnotes::new(p, existing_footnotes);
             let p = TableWrapper::new(p.map(|(ev, _)| ev));
-            CodeBlocks::new(p, codes, edition, playground)
+            CodeBlocks::new(p, codes, edition, playground, highlight_foreign_code)
         })
     }
 
@@ -1427,8 +1444,15 @@ impl<'a> Markdown<'a> {
 
 impl MarkdownWithToc<'_> {
     pub(crate) fn into_parts(self) -> (Toc, String) {
-        let MarkdownWithToc { content: md, links, ids, error_codes: codes, edition, playground } =
-            self;
+        let MarkdownWithToc {
+            content: md,
+            links,
+            ids,
+            error_codes: codes,
+            edition,
+            playground,
+            highlight_foreign_code,
+        } = self;
 
         // This is actually common enough to special-case
         if md.is_empty() {
@@ -1452,7 +1476,7 @@ impl MarkdownWithToc<'_> {
             let p = HeadingLinks::new(p, Some(&mut toc), ids, HeadingOffset::H1);
             let p = footnotes::Footnotes::new(p, existing_footnotes);
             let p = TableWrapper::new(p.map(|(ev, _)| ev));
-            let p = CodeBlocks::new(p, codes, edition, playground);
+            let p = CodeBlocks::new(p, codes, edition, playground, highlight_foreign_code);
             html::push_html(&mut s, p);
         });
 
diff --git a/src/librustdoc/html/markdown/tests.rs b/src/librustdoc/html/markdown/tests.rs
@@ -306,6 +306,7 @@ fn test_header() {
             edition: DEFAULT_EDITION,
             playground: &None,
             heading_offset: HeadingOffset::H2,
+            highlight_foreign_code: false,
         }
         .write_into(&mut output)
         .unwrap();
@@ -359,6 +360,7 @@ fn test_header_ids_multiple_blocks() {
             edition: DEFAULT_EDITION,
             playground: &None,
             heading_offset: HeadingOffset::H2,
+            highlight_foreign_code: false,
         }
         .write_into(&mut output)
         .unwrap();
@@ -510,6 +512,7 @@ fn test_ascii_with_prepending_hashtag() {
             edition: DEFAULT_EDITION,
             playground: &None,
             heading_offset: HeadingOffset::H2,
+            highlight_foreign_code: false,
         }
         .write_into(&mut output)
         .unwrap();
diff --git a/src/librustdoc/html/render/context.rs b/src/librustdoc/html/render/context.rs
@@ -150,6 +150,8 @@ pub(crate) struct SharedContext<'tcx> {
     /// Controls whether we read / write to cci files in the doc root. Defaults read=true,
     /// write=true
     should_merge: ShouldMerge,
+    /// Whether to syntax-highlight non-Rust code blocks using tree-sitter.
+    pub(super) highlight_foreign_code: bool,
 }
 
 impl SharedContext<'_> {
@@ -495,6 +497,7 @@ impl<'tcx> Context<'tcx> {
             call_locations,
             no_emit_shared,
             html_no_source,
+            highlight_foreign_code,
             ..
         } = options;
 
@@ -580,6 +583,7 @@ impl<'tcx> Context<'tcx> {
             call_locations,
             should_merge: options.should_merge,
             expanded_codes,
+            highlight_foreign_code,
         };
 
         let dst = output;
diff --git a/src/librustdoc/html/render/mod.rs b/src/librustdoc/html/render/mod.rs
@@ -651,6 +651,7 @@ fn scrape_examples_help(shared: &SharedContext<'_>) -> String {
             edition: shared.edition(),
             playground: &shared.playground,
             heading_offset: HeadingOffset::H1,
+            highlight_foreign_code: shared.highlight_foreign_code,
         }
         .write_into(f))
     )
@@ -693,6 +694,7 @@ fn render_markdown(
             edition: cx.shared.edition(),
             playground: &cx.shared.playground,
             heading_offset,
+            highlight_foreign_code: cx.shared.highlight_foreign_code,
         }
         .write_into(&mut *f)?;
         f.write_str("</div>")
@@ -2164,6 +2166,7 @@ fn render_impl(
                         edition: cx.shared.edition(),
                         playground: &cx.shared.playground,
                         heading_offset: HeadingOffset::H4,
+                        highlight_foreign_code: cx.shared.highlight_foreign_code,
                     }
                     .split_summary_and_content()
                 })
diff --git a/src/librustdoc/html/render/sidebar.rs b/src/librustdoc/html/render/sidebar.rs
@@ -229,6 +229,7 @@ fn docblock_toc<'a>(
         error_codes: cx.shared.codes,
         edition: cx.shared.edition(),
         playground: &cx.shared.playground,
+        highlight_foreign_code: cx.shared.highlight_foreign_code,
     }
     .into_parts();
     let links: Vec<Link<'_>> = toc
diff --git a/src/librustdoc/lib.rs b/src/librustdoc/lib.rs
@@ -654,6 +654,14 @@ fn opts() -> Vec<RustcOptGroup> {
             "Add possibility to expand macros in the HTML source code pages",
             "",
         ),
+        opt(
+            Unstable,
+            Flag,
+            "",
+            "highlight-foreign-code",
+            "Syntax-highlight non-Rust code blocks using tree-sitter (arborium)",
+            "",
+        ),
         // deprecated / removed options
         opt(
             Stable,
diff --git a/src/librustdoc/markdown.rs b/src/librustdoc/markdown.rs
@@ -87,6 +87,7 @@ pub(crate) fn render_and_write<P: AsRef<Path>>(
                 error_codes,
                 edition,
                 playground: &playground,
+                highlight_foreign_code: options.highlight_foreign_code,
             }
             .write_into(f)
         } else {
@@ -98,6 +99,7 @@ pub(crate) fn render_and_write<P: AsRef<Path>>(
                 edition,
                 playground: &playground,
                 heading_offset: HeadingOffset::H1,
+                highlight_foreign_code: options.highlight_foreign_code,
             }
             .write_into(f)
         }

Original file line number	Diff line number	Diff line change
`@@ -651,6 +651,7 @@ fn scrape_examples_help(shared: &SharedContext<'_>) -> String {`
`651`	`651`	`edition: shared.edition(),`
`652`	`652`	`playground: &shared.playground,`
`653`	`653`	`heading_offset: HeadingOffset::H1,`
	`654`	`+ highlight_foreign_code: shared.highlight_foreign_code,`
`654`	`655`	`}`
`655`	`656`	`.write_into(f))`
`656`	`657`	`)`
`@@ -693,6 +694,7 @@ fn render_markdown(`
`693`	`694`	`edition: cx.shared.edition(),`
`694`	`695`	`playground: &cx.shared.playground,`
`695`	`696`	`heading_offset,`
	`697`	`+ highlight_foreign_code: cx.shared.highlight_foreign_code,`
`696`	`698`	`}`
`697`	`699`	`.write_into(&mut *f)?;`
`698`	`700`	`f.write_str("</div>")`
`@@ -2164,6 +2166,7 @@ fn render_impl(`
`2164`	`2166`	`edition: cx.shared.edition(),`
`2165`	`2167`	`playground: &cx.shared.playground,`
`2166`	`2168`	`heading_offset: HeadingOffset::H4,`
	`2169`	`+ highlight_foreign_code: cx.shared.highlight_foreign_code,`
`2167`	`2170`	`}`
`2168`	`2171`	`.split_summary_and_content()`
`2169`	`2172`	`})`
Original file line number	Diff line number	Diff line change
`@@ -229,6 +229,7 @@ fn docblock_toc<'a>(`
`229`	`229`	`error_codes: cx.shared.codes,`
`230`	`230`	`edition: cx.shared.edition(),`
`231`	`231`	`playground: &cx.shared.playground,`
	`232`	`+ highlight_foreign_code: cx.shared.highlight_foreign_code,`
`232`	`233`	`}`
`233`	`234`	`.into_parts();`
`234`	`235`	`let links: Vec<Link<'_>> = toc`
Original file line number	Diff line number	Diff line change
`@@ -87,6 +87,7 @@ pub(crate) fn render_and_write<P: AsRef<Path>>(`
`87`	`87`	`error_codes,`
`88`	`88`	`edition,`
`89`	`89`	`playground: &playground,`
	`90`	`+ highlight_foreign_code: options.highlight_foreign_code,`
`90`	`91`	`}`
`91`	`92`	`.write_into(f)`
`92`	`93`	`} else {`
`@@ -98,6 +99,7 @@ pub(crate) fn render_and_write<P: AsRef<Path>>(`
`98`	`99`	`edition,`
`99`	`100`	`playground: &playground,`
`100`	`101`	`heading_offset: HeadingOffset::H1,`
	`102`	`+ highlight_foreign_code: options.highlight_foreign_code,`
`101`	`103`	`}`
`102`	`104`	`.write_into(f)`
`103`	`105`	`}`