feat(html): better formatting for code & backport changes from deno-docs (#611)

Author: crowlKats

src/html/comrak_adapters.rs

@@ -232,42 +232,24 @@ pub struct ToCEntry {
   pub anchor: String,
 }
 
-#[derive(Debug)]
-pub struct ToCGroup {
-  pub toc: Vec<ToCEntry>,
-  pub id: Option<String>,
-}
-
 #[derive(Clone)]
 pub struct HeadingToCAdapter {
-  toc_groups: Arc<Mutex<Vec<ToCGroup>>>,
+  toc: Arc<Mutex<Vec<ToCEntry>>>,
   anchorizer: Arc<Mutex<comrak::html::Anchorizer>>,
   offset: Arc<Mutex<u8>>,
 }
 
 impl Default for HeadingToCAdapter {
   fn default() -> Self {
     Self {
-      toc_groups: Arc::new(Mutex::new(vec![ToCGroup {
-        toc: vec![],
-        id: None,
-      }])),
+      toc: Arc::new(Mutex::new(vec![])),
       anchorizer: Arc::new(Mutex::new(Default::default())),
       offset: Arc::new(Mutex::new(0)),
     }
   }
 }
 
 impl HeadingToCAdapter {
-  pub fn create_group(&self, id: String) {
-    let mut toc_groups = self.toc_groups.lock().unwrap();
-
-    toc_groups.push(ToCGroup {
-      toc: vec![],
-      id: Some(id),
-    });
-  }
-
   pub fn anchorize(&self, content: String) -> String {
     let mut anchorizer = self.anchorizer.lock().unwrap();
     anchorizer.anchorize(content.clone())
@@ -279,19 +261,13 @@ impl HeadingToCAdapter {
     content: String,
     anchor: String,
   ) -> String {
-    let mut toc_groups = self.toc_groups.lock().unwrap();
+    let mut toc = self.toc.lock().unwrap();
     let mut offset = self.offset.lock().unwrap();
 
     *offset = level;
 
-    let toc_group = toc_groups.last_mut().unwrap();
-
-    if toc_group
-      .toc
-      .last()
-      .map_or(true, |toc| toc.content != content)
-    {
-      toc_group.toc.push(ToCEntry {
+    if toc.last().map_or(true, |toc| toc.content != content) {
+      toc.push(ToCEntry {
         level,
         content,
         anchor: anchor.clone(),
@@ -301,64 +277,37 @@ impl HeadingToCAdapter {
     anchor
   }
 
-  pub fn into_toc(self) -> Vec<ToCGroup> {
-    Arc::into_inner(self.toc_groups)
-      .unwrap()
-      .into_inner()
-      .unwrap()
-  }
-
   pub fn render(self) -> Option<String> {
-    let toc_groups = Arc::into_inner(self.toc_groups)
-      .unwrap()
-      .into_inner()
-      .unwrap();
+    let toc = Arc::into_inner(self.toc).unwrap().into_inner().unwrap();
 
-    if toc_groups.is_empty()
-      || (toc_groups.len() == 1 && toc_groups[0].toc.is_empty())
-    {
+    if toc.is_empty() {
       return None;
     }
 
-    let mut toc_content = vec![];
+    let mut toc_content = vec!["<ul>".to_string()];
+    let mut current_level = toc.first().unwrap().level;
 
-    for toc_group in toc_groups {
-      if toc_group.toc.is_empty() {
-        continue;
+    for entry in toc {
+      match current_level.cmp(&entry.level) {
+        Ordering::Equal => {}
+        Ordering::Less => {
+          toc_content.push(r#"<li><ul>"#.to_string());
+          current_level = entry.level;
+        }
+        Ordering::Greater => {
+          toc_content.push("</ul></li>".to_string());
+          current_level = entry.level;
+        }
       }
 
       toc_content.push(format!(
-        r#"<ul{}>"#,
-        toc_group
-          .id
-          .map(|id| format!(r#" id="{id}""#))
-          .unwrap_or_default(),
+        r##"<li><a href="#{}" title="{}">{}</a></li>"##,
+        entry.anchor, entry.content, entry.content
       ));
-
-      let mut current_level = 1;
-
-      for entry in toc_group.toc {
-        match current_level.cmp(&entry.level) {
-          Ordering::Equal => {}
-          Ordering::Less => {
-            toc_content.push(r#"<li><ul>"#.to_string());
-            current_level = entry.level;
-          }
-          Ordering::Greater => {
-            toc_content.push("</ul></li>".to_string());
-            current_level = entry.level;
-          }
-        }
-
-        toc_content.push(format!(
-          r##"<li><a href="#{}" title="{}">{}</a></li>"##,
-          entry.anchor, entry.content, entry.content
-        ));
-      }
-
-      toc_content.push(String::from("</ul>"));
     }
 
+    toc_content.push(String::from("</ul>"));
+
     Some(toc_content.join(""))
   }
 }
@@ -376,8 +325,8 @@ impl HeadingAdapter for HeadingToCAdapter {
     let anchor = anchorizer.anchorize(heading.content.clone());
     writeln!(output, r#"<h{} id="{anchor}">"#, heading.level)?;
 
-    let mut lock = self.toc_groups.lock().unwrap();
-    lock.last_mut().unwrap().toc.push(ToCEntry {
+    let mut toc = self.toc.lock().unwrap();
+    toc.push(ToCEntry {
       level: heading.level + *offset,
       content: heading.content.clone(),
       anchor,

src/html/jsdoc.rs

@@ -306,6 +306,7 @@ fn render_node<'a>(
 pub struct MarkdownToHTMLOptions {
   pub summary: bool,
   pub summary_prefer_title: bool,
+  pub no_toc: bool,
 }
 
 pub fn markdown_to_html(
@@ -334,7 +335,9 @@ pub fn markdown_to_html(
   let mut plugins = comrak::Plugins::default();
   plugins.render.codefence_syntax_highlighter =
     Some(&render_ctx.ctx.highlight_adapter);
-  plugins.render.heading_adapter = Some(&render_ctx.toc);
+  if !render_options.no_toc {
+    plugins.render.heading_adapter = Some(&render_ctx.toc);
+  }
 
   let md = parse_links(md, render_ctx);
 
@@ -448,18 +451,24 @@ pub(crate) fn render_markdown_summary(
     MarkdownToHTMLOptions {
       summary: true,
       summary_prefer_title: true,
+      no_toc: false,
     },
   )
   .unwrap_or_default()
 }
 
-pub(crate) fn render_markdown(render_ctx: &RenderContext, md: &str) -> String {
+pub(crate) fn render_markdown(
+  render_ctx: &RenderContext,
+  md: &str,
+  no_toc: bool,
+) -> String {
   markdown_to_html(
     render_ctx,
     md,
     MarkdownToHTMLOptions {
       summary: false,
       summary_prefer_title: false,
+      no_toc,
     },
   )
   .unwrap_or_default()
@@ -477,6 +486,7 @@ pub(crate) fn jsdoc_body_to_html(
       MarkdownToHTMLOptions {
         summary,
         summary_prefer_title: true,
+        no_toc: false,
       },
     )
   } else {
@@ -537,7 +547,8 @@ impl ExampleCtx {
     };
 
     let markdown_title = render_markdown_summary(render_ctx, &title);
-    let markdown_body = render_markdown(render_ctx, body.unwrap_or_default());
+    let markdown_body =
+      render_markdown(render_ctx, body.unwrap_or_default(), true);
 
     ExampleCtx {
       anchor: AnchorCtx { id: id.to_string() },
@@ -571,6 +582,7 @@ impl ModuleDocCtx {
           Some(render_markdown(
             render_ctx,
             doc.as_deref().unwrap_or_default(),
+            false,
           ))
         } else {
           None
@@ -861,6 +873,7 @@ mod test {
       > foo
       >
       > bar"#,
+      true,
     );
 
     assert!(md.contains("foo"));
@@ -874,6 +887,7 @@ mod test {
       > foo
       >
       > bar"#,
+      true,
     );
 
     assert!(md.contains("foo"));

src/html/pages.rs

@@ -280,9 +280,23 @@ impl IndexCtx {
               render_ctx.toc.anchorize(title.clone()),
             );
 
-            let doc = ctx.category_docs.as_ref().and_then(|category_docs| {
-              category_docs.get(&title).cloned().flatten()
-            });
+            let doc = ctx
+              .category_docs
+              .as_ref()
+              .and_then(|category_docs| {
+                category_docs.get(&title).cloned().flatten()
+              })
+              .and_then(|doc| {
+                super::jsdoc::markdown_to_html(
+                  &render_ctx,
+                  &doc,
+                  super::jsdoc::MarkdownToHTMLOptions {
+                    summary: false,
+                    summary_prefer_title: false,
+                    no_toc: false,
+                  },
+                )
+              });
 
             util::SectionCtx {
               header: SectionHeaderCtx {

src/html/parameters.rs

@@ -9,20 +9,13 @@ pub(crate) fn render_params(
 ) -> String {
   if params.is_empty() {
     String::new()
-  } else if params.len() <= 3 {
-    let items = params
-      .iter()
-      .enumerate()
-      .map(|(i, element)| render_param(ctx, element, i))
-      .collect::<Vec<String>>()
-      .join("<span>, </span>");
-
-    format!("<span>{items}</span>")
+  } else if params.len() == 1 {
+    format!("<span>{}</span>", render_param(ctx, &params[0], 0))
   } else {
     let mut items = Vec::with_capacity(params.len());
 
     for (i, def) in params.iter().enumerate() {
-      items.push(format!("<div>{}</div>", render_param(ctx, def, i)));
+      items.push(format!("<div>{},</div>", render_param(ctx, def, i)));
     }
 
     let content = items.join("");

src/html/render_context.rs

@@ -265,27 +265,28 @@ impl<'ctx> RenderContext<'ctx> {
           });
         }
 
-        let (_, symbol_parts) = symbol.split('.').enumerate().fold(
-          (vec![], vec![]),
-          |(mut symbol_parts, mut breadcrumbs), (i, symbol_part)| {
-            symbol_parts.push(symbol_part);
-            let breadcrumb = BreadcrumbCtx {
-              name: symbol_part.to_string(),
-              href: self.ctx.resolve_path(
-                self.current_resolve,
-                UrlResolveKind::Symbol {
-                  file,
-                  symbol: &symbol_parts.join("."),
-                },
-              ),
-              is_symbol: true,
-              is_first_symbol: i == 0,
-            };
-            breadcrumbs.push(breadcrumb);
-
-            (symbol_parts, breadcrumbs)
-          },
-        );
+        let (_, symbol_parts) =
+          split_with_brackets(symbol).into_iter().enumerate().fold(
+            (vec![], vec![]),
+            |(mut symbol_parts, mut breadcrumbs), (i, symbol_part)| {
+              symbol_parts.push(symbol_part.clone());
+              let breadcrumb = BreadcrumbCtx {
+                name: symbol_part,
+                href: self.ctx.resolve_path(
+                  self.current_resolve,
+                  UrlResolveKind::Symbol {
+                    file,
+                    symbol: &symbol_parts.join("."),
+                  },
+                ),
+                is_symbol: true,
+                is_first_symbol: i == 0,
+              };
+              breadcrumbs.push(breadcrumb);
+
+              (symbol_parts, breadcrumbs)
+            },
+          );
 
         parts.extend(symbol_parts);
 
@@ -297,6 +298,41 @@ impl<'ctx> RenderContext<'ctx> {
   }
 }
 
+fn split_with_brackets(s: &str) -> Vec<String> {
+  let mut result = Vec::new();
+  let mut current = String::new();
+  let mut bracket = false;
+
+  for c in s.chars() {
+    if c == ']' {
+      bracket = false;
+      current.push(c);
+      result.push(current.clone());
+      current.clear();
+    } else if c == '[' {
+      bracket = true;
+      if !current.is_empty() {
+        result.push(current.clone());
+        current.clear();
+      }
+      current.push(c);
+    } else if c == '.' && !bracket {
+      if !current.is_empty() {
+        result.push(current.clone());
+        current.clear();
+      }
+    } else {
+      current.push(c);
+    }
+  }
+
+  if !current.is_empty() {
+    result.push(current.clone());
+  }
+
+  result
+}
+
 fn get_current_imports(
   doc_nodes: &[DocNodeWithContext],
 ) -> HashMap<String, String> {