rustdoc/html/
layout.rs

1use std::fmt::Display;
2use std::path::PathBuf;
3
4use askama::Template;
5use rustc_data_structures::fx::FxIndexMap;
6
7use super::static_files::{STATIC_FILES, StaticFiles};
8use crate::externalfiles::ExternalHtml;
9use crate::html::render::{StylePath, ensure_trailing_slash};
10
11#[cfg(test)]
12mod tests;
13
14pub(crate) struct Layout {
15    pub(crate) logo: String,
16    pub(crate) favicon: String,
17    pub(crate) external_html: ExternalHtml,
18    pub(crate) default_settings: FxIndexMap<String, String>,
19    pub(crate) krate: String,
20    pub(crate) krate_version: String,
21    /// The given user css file which allow to customize the generated
22    /// documentation theme.
23    pub(crate) css_file_extension: Option<PathBuf>,
24    /// If true, then scrape-examples.js will be included in the output HTML file
25    pub(crate) scrape_examples_extension: bool,
26}
27
28pub(crate) struct Page<'a> {
29    pub(crate) title: &'a str,
30    pub(crate) short_title: &'a str,
31    pub(crate) css_class: &'a str,
32    pub(crate) root_path: &'a str,
33    pub(crate) static_root_path: Option<&'a str>,
34    pub(crate) description: &'a str,
35    pub(crate) resource_suffix: &'a str,
36    pub(crate) rust_logo: bool,
37}
38
39impl Page<'_> {
40    pub(crate) fn get_static_root_path(&self) -> String {
41        match self.static_root_path {
42            Some(s) => s.to_string(),
43            None => format!("{}static.files/", self.root_path),
44        }
45    }
46}
47
48#[derive(Template)]
49#[template(path = "page.html")]
50struct PageLayout<'a> {
51    static_root_path: String,
52    page: &'a Page<'a>,
53    layout: &'a Layout,
54
55    files: &'static StaticFiles,
56
57    themes: Vec<String>,
58    sidebar: String,
59    content: String,
60    rust_channel: &'static str,
61    pub(crate) rustdoc_version: &'a str,
62    // same as layout.krate, except on top-level pages like
63    // Settings, Help, All Crates, and About Scraped Examples,
64    // where these things instead give Rustdoc name and version.
65    //
66    // These are separate from the variables used for the search
67    // engine, because "Rustdoc" isn't necessarily a crate in
68    // the current workspace.
69    display_krate: &'a str,
70    display_krate_with_trailing_slash: String,
71    display_krate_version_number: &'a str,
72    display_krate_version_extra: &'a str,
73}
74
75impl PageLayout<'_> {
76    /// See [`may_remove_crossorigin`].
77    fn static_root_path_may_remove_crossorigin(&self) -> bool {
78        may_remove_crossorigin(&self.static_root_path)
79    }
80}
81
82pub(crate) use crate::html::render::sidebar::filters;
83
84pub(crate) fn render<T: Display, S: Display>(
85    layout: &Layout,
86    page: &Page<'_>,
87    sidebar: S,
88    t: T,
89    style_files: &[StylePath],
90) -> String {
91    let rustdoc_version = rustc_interface::util::version_str!().unwrap_or("unknown version");
92
93    let (display_krate, display_krate_version, display_krate_with_trailing_slash) =
94        if page.root_path == "./" {
95            // top level pages use Rust branding
96            ("Rustdoc", rustdoc_version, String::new())
97        } else {
98            let display_krate_with_trailing_slash =
99                ensure_trailing_slash(&layout.krate).to_string();
100            (&layout.krate[..], &layout.krate_version[..], display_krate_with_trailing_slash)
101        };
102    let static_root_path = page.get_static_root_path();
103
104    // bootstrap passes in parts of the version separated by tabs, but other stuff might use spaces
105    let (display_krate_version_number, display_krate_version_extra) =
106        display_krate_version.split_once([' ', '\t']).unwrap_or((display_krate_version, ""));
107
108    let mut themes: Vec<String> = style_files.iter().map(|s| s.basename().unwrap()).collect();
109    themes.sort();
110
111    let content = t.to_string(); // Note: This must happen before making the sidebar.
112    let sidebar = sidebar.to_string();
113    PageLayout {
114        static_root_path,
115        page,
116        layout,
117        files: &STATIC_FILES,
118        themes,
119        sidebar,
120        content,
121        display_krate,
122        display_krate_with_trailing_slash,
123        display_krate_version_number,
124        display_krate_version_extra,
125        rust_channel: *crate::clean::utils::RUSTDOC_VERSION,
126        rustdoc_version,
127    }
128    .render()
129    .unwrap()
130}
131
132pub(crate) fn redirect(url: &str) -> String {
133    // <script> triggers a redirect before refresh, so this is fine.
134    format!(
135        r##"<!DOCTYPE html>
136<html lang="en">
137<head>
138    <meta http-equiv="refresh" content="0;URL={url}">
139    <title>Redirection</title>
140</head>
141<body>
142    <p>Redirecting to <a href="{url}">{url}</a>...</p>
143    <script>location.replace("{url}" + location.search + location.hash);</script>
144</body>
145</html>"##,
146    )
147}
148
149/// Conservatively determines if `href` is relative to the current origin,
150/// so that `crossorigin` may be safely removed from `<link>` elements.
151pub(crate) fn may_remove_crossorigin(href: &str) -> bool {
152    // Reject scheme-relative URLs (`//example.com/`).
153    if href.starts_with("//") {
154        return false;
155    }
156    // URL is interpreted as having a scheme iff: it starts with an ascii alpha, and only
157    // contains ascii alphanumeric or `+` `-` `.` up to the `:`.
158    // https://url.spec.whatwg.org/#url-parsing
159    let has_scheme = href.split_once(':').is_some_and(|(scheme, _rest)| {
160        let mut chars = scheme.chars();
161        chars.next().is_some_and(|c| c.is_ascii_alphabetic())
162            && chars.all(|c| c.is_ascii_alphanumeric() || c == '+' || c == '-' || c == '.')
163    });
164    // Reject anything with a scheme (`http:`, etc.).
165    !has_scheme
166}
rustdoc/html/layout.rs

rustdoc/html/
layout.rs
