add mechanism for injecting content into the html head

Author: crowlKats

examples/ddoc/main.rs

@@ -263,6 +263,7 @@ fn generate_docs_directory(
       None, None, None,
     ),
     markdown_stripper: Rc::new(deno_doc::html::comrak::strip),
+    head_inject: None,
   };
   let html = deno_doc::html::generate(options, doc_nodes_by_url)?;
 

src/html/jsdoc.rs

@@ -487,6 +487,7 @@ mod test {
           None, None, None,
         ),
         markdown_stripper: Rc::new(crate::html::comrak::strip),
+        head_inject: None,
       },
       Default::default(),
       Default::default(),
@@ -647,6 +648,7 @@ mod test {
           None, None, None,
         ),
         markdown_stripper: Rc::new(crate::html::comrak::strip),
+        head_inject: None,
       },
       Default::default(),
       Default::default(),

src/html/mod.rs

@@ -228,6 +228,8 @@ lazy_static! {
   pub static ref HANDLEBARS: Handlebars<'static> = setup_hbs().unwrap();
 }
 
+pub type HeadInject = Rc<dyn Fn(&str) -> String>;
+
 #[derive(Clone)]
 pub struct GenerateOptions {
   /// The name that is shown is the top-left corner, eg. "deno_std".
@@ -245,6 +247,7 @@ pub struct GenerateOptions {
   pub default_symbol_map: Option<IndexMap<String, String>>,
   pub markdown_renderer: jsdoc::MarkdownRenderer,
   pub markdown_stripper: jsdoc::MarkdownStripper,
+  pub head_inject: Option<HeadInject>,
 }
 
 #[non_exhaustive]
@@ -263,6 +266,7 @@ pub struct GenerateCtx {
   pub default_symbol_map: Option<IndexMap<String, String>>,
   pub markdown_renderer: jsdoc::MarkdownRenderer,
   pub markdown_stripper: jsdoc::MarkdownStripper,
+  pub head_inject: Option<HeadInject>,
 }
 
 impl GenerateCtx {
@@ -368,6 +372,7 @@ impl GenerateCtx {
       default_symbol_map: options.default_symbol_map,
       markdown_renderer: options.markdown_renderer,
       markdown_stripper: options.markdown_stripper,
+      head_inject: options.head_inject,
     })
   }
 
@@ -927,11 +932,10 @@ pub fn generate(
             title_parts.pop();
 
             let html_head_ctx = pages::HtmlHeadCtx::new(
+              &ctx,
               &root,
               Some(&title_parts.join(" - ")),
-              ctx.package_name.as_ref(),
               Some(short_path),
-              ctx.disable_search,
             );
 
             let file_name =

src/html/pages.rs

@@ -39,24 +39,26 @@ pub struct HtmlHeadCtx {
   script_js: String,
   fuse_js: String,
   url_search: String,
+  head_inject: Option<String>,
   disable_search: bool,
 }
 
 impl HtmlHeadCtx {
   pub const TEMPLATE: &'static str = "pages/html_head";
 
   pub fn new(
+    ctx: &GenerateCtx,
     root: &str,
     page: Option<&str>,
-    package_name: Option<&String>,
     current_file: Option<&ShortPath>,
-    disable_search: bool,
   ) -> Self {
     Self {
       title: format!(
         "{}{}documentation",
         page.map(|page| format!("{page} - ")).unwrap_or_default(),
-        package_name
+        ctx
+          .package_name
+          .as_ref()
           .map(|package_name| format!("{package_name} "))
           .unwrap_or_default()
       ),
@@ -71,7 +73,8 @@ impl HtmlHeadCtx {
       script_js: format!("{root}{SCRIPT_FILENAME}"),
       fuse_js: format!("{root}{FUSE_FILENAME}"),
       url_search: format!("{root}{SEARCH_FILENAME}"),
-      disable_search,
+      head_inject: ctx.head_inject.clone().map(|head_inject| head_inject(root)),
+      disable_search: ctx.disable_search,
     }
   }
 }
@@ -232,6 +235,7 @@ impl IndexCtx {
       ctx.resolve_path(render_ctx.get_current_resolve(), UrlResolveKind::Root);
 
     let html_head_ctx = HtmlHeadCtx::new(
+      ctx,
       &root,
       short_path.as_ref().and_then(|short_path| {
         if short_path.is_main {
@@ -240,9 +244,7 @@ impl IndexCtx {
           Some(short_path.display_name())
         }
       }),
-      ctx.package_name.as_ref(),
       None,
-      ctx.disable_search,
     );
 
     let overview = match ctx.file_mode {
@@ -399,13 +401,7 @@ impl IndexCtx {
     let root =
       ctx.resolve_path(UrlResolveKind::Category(name), UrlResolveKind::Root);
 
-    let html_head_ctx = HtmlHeadCtx::new(
-      &root,
-      Some(name),
-      ctx.package_name.as_ref(),
-      None,
-      ctx.disable_search,
-    );
+    let html_head_ctx = HtmlHeadCtx::new(ctx, &root, Some(name), None);
 
     let breadcrumbs_ctx = render_ctx.get_breadcrumbs();
 
@@ -463,13 +459,7 @@ impl AllSymbolsCtx {
       }),
     );
 
-    let html_head_ctx = HtmlHeadCtx::new(
-      "./",
-      Some("All Symbols"),
-      ctx.package_name.as_ref(),
-      None,
-      ctx.disable_search,
-    );
+    let html_head_ctx = HtmlHeadCtx::new(ctx, "./", Some("All Symbols"), None);
 
     let categories_panel = CategoriesPanelCtx::new(&render_ctx, None);
 

src/html/render_context.rs

@@ -601,6 +601,7 @@ mod test {
           None, None, None,
         ),
         markdown_stripper: Rc::new(crate::html::comrak::strip),
+        head_inject: None,
       },
       None,
       Default::default(),

src/html/templates/pages/html_head.hbs

@@ -8,13 +8,14 @@
   <link rel="stylesheet" href="{{stylesheet_url}}">
   <link rel="stylesheet" href="{{page_stylesheet_url}}">
   <link id="ddocResetStylesheet" rel="stylesheet" href="{{reset_stylesheet_url}}">
+  {{{~head_inject~}}}
 
-  {{#if (not disable_search)}}
+  {{~#if (not disable_search)~}}
     <script src="{{url_search_index}}" defer></script>
     <script src="{{script_js}}" defer></script>
     <script src="{{fuse_js}}" defer></script>
     <script src="{{url_search}}" defer></script>
-  {{/if}}
+  {{~/if~}}
 </head>
 <body>
 <div class="ddoc">

tests/html_test.rs

@@ -175,6 +175,7 @@ async fn html_doc_files() {
       default_symbol_map: None,
       markdown_renderer: comrak::create_renderer(None, None, None),
       markdown_stripper: Rc::new(comrak::strip),
+      head_inject: None,
     },
     get_files("single").await,
   )
@@ -249,6 +250,7 @@ async fn html_doc_files_rewrite() {
       default_symbol_map: None,
       markdown_renderer: comrak::create_renderer(None, None, None),
       markdown_stripper: Rc::new(comrak::strip),
+      head_inject: None,
     },
     get_files("multiple").await,
   )
@@ -358,6 +360,7 @@ async fn symbol_group() {
       default_symbol_map: None,
       markdown_renderer: comrak::create_renderer(None, None, None),
       markdown_stripper: Rc::new(comrak::strip),
+      head_inject: None,
     },
     None,
     Default::default(),
@@ -389,11 +392,10 @@ async fn symbol_group() {
             );
 
             let html_head_ctx = pages::HtmlHeadCtx::new(
+              &ctx,
               &root,
               Some(&symbol_group_ctx.name),
-              ctx.package_name.as_ref(),
               Some(short_path),
-              false,
             );
 
             Some(pages::SymbolPageCtx {
@@ -449,6 +451,7 @@ async fn symbol_search() {
       default_symbol_map: None,
       markdown_renderer: comrak::create_renderer(None, None, None),
       markdown_stripper: Rc::new(comrak::strip),
+      head_inject: None,
     },
     None,
     Default::default(),
@@ -496,6 +499,7 @@ async fn module_doc() {
       default_symbol_map: None,
       markdown_renderer: comrak::create_renderer(None, None, None),
       markdown_stripper: Rc::new(comrak::strip),
+      head_inject: None,
     },
     None,
     FileMode::Single,

tests/snapshots/html_test__html_doc_files-2.snap

@@ -11,13 +11,10 @@ expression: "files.get(\"./index.html\").unwrap()"
   <meta name="doc-current-file" content="">
   <link rel="stylesheet" href="styles.css">
   <link rel="stylesheet" href="page.css">
-  <link id="ddocResetStylesheet" rel="stylesheet" href="reset.css">
-
-    <script src="search_index.js" defer></script>
+  <link id="ddocResetStylesheet" rel="stylesheet" href="reset.css"><script src="search_index.js" defer></script>
     <script src="script.js" defer></script>
     <script src="fuse.js" defer></script>
-    <script src="search.js" defer></script>
-</head>
+    <script src="search.js" defer></script></head>
 <body>
 <div class="ddoc">
 <div><nav class="top-0 sticky bg-white z-50 py-3 h-14" id="topnav">

tests/snapshots/html_test__html_doc_files-3.snap

@@ -11,13 +11,10 @@ expression: "files.get(\"./~/Bar.html\").unwrap()"
   <meta name="doc-current-file" content=".">
   <link rel="stylesheet" href="..&#x2F;styles.css">
   <link rel="stylesheet" href="..&#x2F;page.css">
-  <link id="ddocResetStylesheet" rel="stylesheet" href="..&#x2F;reset.css">
-
-    <script src="..&#x2F;search_index.js" defer></script>
+  <link id="ddocResetStylesheet" rel="stylesheet" href="..&#x2F;reset.css"><script src="..&#x2F;search_index.js" defer></script>
     <script src="..&#x2F;script.js" defer></script>
     <script src="..&#x2F;fuse.js" defer></script>
-    <script src="..&#x2F;search.js" defer></script>
-</head>
+    <script src="..&#x2F;search.js" defer></script></head>
 <body>
 <div class="ddoc">
 <div><nav class="top-0 sticky bg-white z-50 py-3 h-14" id="topnav">

tests/snapshots/html_test__html_doc_files-5.snap

@@ -11,13 +11,10 @@ expression: "files.get(\"./~/Foo.html\").unwrap()"
   <meta name="doc-current-file" content=".">
   <link rel="stylesheet" href="..&#x2F;styles.css">
   <link rel="stylesheet" href="..&#x2F;page.css">
-  <link id="ddocResetStylesheet" rel="stylesheet" href="..&#x2F;reset.css">
-
-    <script src="..&#x2F;search_index.js" defer></script>
+  <link id="ddocResetStylesheet" rel="stylesheet" href="..&#x2F;reset.css"><script src="..&#x2F;search_index.js" defer></script>
     <script src="..&#x2F;script.js" defer></script>
     <script src="..&#x2F;fuse.js" defer></script>
-    <script src="..&#x2F;search.js" defer></script>
-</head>
+    <script src="..&#x2F;search.js" defer></script></head>
 <body>
 <div class="ddoc">
 <div><nav class="top-0 sticky bg-white z-50 py-3 h-14" id="topnav">