feat(html): remove sidepanels and add document navigation (#569)

Author: crowlKats

src/html/comrak_adapters.rs

@@ -7,6 +7,7 @@ use comrak::adapters::HeadingAdapter;
 use comrak::adapters::HeadingMeta;
 use comrak::adapters::SyntaxHighlighterAdapter;
 use comrak::nodes::Sourcepos;
+use std::cmp::Ordering;
 use std::collections::HashMap;
 use std::io::Write;
 use std::sync::Arc;
@@ -224,15 +225,75 @@ impl SyntaxHighlighterAdapter for HighlightAdapter {
   }
 }
 
-#[derive(Default)]
+#[derive(Debug)]
+pub struct ToCEntry {
+  pub level: u8,
+  pub content: String,
+  pub anchor: String,
+}
+
+#[derive(Default, Clone)]
 pub struct HeadingToCAdapter {
-  toc: Mutex<Vec<(u8, String, String)>>,
-  anchorizer: Mutex<comrak::html::Anchorizer>,
+  toc: Arc<Mutex<Vec<ToCEntry>>>,
+  anchorizer: Arc<Mutex<comrak::html::Anchorizer>>,
+  offset: Arc<Mutex<u8>>,
 }
 
 impl HeadingToCAdapter {
-  pub fn into_toc(self) -> Vec<(u8, String, String)> {
-    self.toc.into_inner().unwrap()
+  pub fn add_entry(&self, level: u8, content: String) -> String {
+    let mut lock = self.toc.lock().unwrap();
+    let mut anchorizer = self.anchorizer.lock().unwrap();
+    let mut offset = self.offset.lock().unwrap();
+
+    let anchor = anchorizer.anchorize(content.clone());
+    *offset = level;
+
+    lock.push(ToCEntry {
+      level,
+      content,
+      anchor: anchor.clone(),
+    });
+
+    anchor
+  }
+
+  pub fn into_toc(self) -> Vec<ToCEntry> {
+    Arc::into_inner(self.toc).unwrap().into_inner().unwrap()
+  }
+
+  pub fn render(self) -> Option<String> {
+    let toc = Arc::into_inner(self.toc).unwrap().into_inner().unwrap();
+
+    if toc.is_empty() {
+      return None;
+    }
+
+    let mut toc_content = vec![String::from(r#"<ul>"#)];
+
+    let mut current_level = 1;
+
+    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##"<li><a href="#{}" title="{}">{}</a></li>"##,
+        entry.anchor, entry.content, entry.content
+      ));
+    }
+
+    toc_content.push(String::from("</ul>"));
+
+    Some(toc_content.join(""))
   }
 }
 
@@ -244,12 +305,17 @@ impl HeadingAdapter for HeadingToCAdapter {
     _sourcepos: Option<Sourcepos>,
   ) -> std::io::Result<()> {
     let mut anchorizer = self.anchorizer.lock().unwrap();
+    let offset = self.offset.lock().unwrap();
 
     let anchor = anchorizer.anchorize(heading.content.clone());
     writeln!(output, r#"<h{} id="{anchor}">"#, heading.level)?;
 
     let mut lock = self.toc.lock().unwrap();
-    lock.push((heading.level, heading.content.clone(), anchor));
+    lock.push(ToCEntry {
+      level: heading.level + *offset,
+      content: heading.content.clone(),
+      anchor,
+    });
 
     Ok(())
   }

src/html/jsdoc.rs

@@ -1,6 +1,5 @@
 use super::render_context::RenderContext;
 use super::util::*;
-use crate::html::usage::UsagesCtx;
 use crate::html::ShortPath;
 use crate::js_doc::JsDoc;
 use crate::js_doc::JsDocTag;
@@ -13,7 +12,6 @@ use comrak::Arena;
 use serde::Serialize;
 use std::borrow::Cow;
 use std::cell::RefCell;
-use std::cmp::Ordering;
 
 #[cfg(feature = "ammonia")]
 use crate::html::comrak_adapters::URLRewriter;
@@ -247,23 +245,16 @@ fn render_node<'a>(
   String::from_utf8(bw.into_inner().unwrap()).unwrap()
 }
 
-#[derive(Debug, Serialize, Clone, Default)]
-pub struct Markdown {
-  pub html: String,
-  pub toc: Option<String>,
-}
-
 pub struct MarkdownToHTMLOptions {
   pub summary: bool,
   pub summary_prefer_title: bool,
-  pub render_toc: bool,
 }
 
 pub fn markdown_to_html(
   render_ctx: &RenderContext,
   md: &str,
   render_options: MarkdownToHTMLOptions,
-) -> Option<Markdown> {
+) -> Option<String> {
   // TODO(bartlomieju): this should be initialized only once
   let mut options = comrak::Options::default();
   options.extension.autolink = true;
@@ -285,9 +276,7 @@ pub fn markdown_to_html(
   let mut plugins = comrak::Plugins::default();
   plugins.render.codefence_syntax_highlighter =
     Some(&render_ctx.ctx.highlight_adapter);
-  let heading_adapter =
-    crate::html::comrak_adapters::HeadingToCAdapter::default();
-  plugins.render.heading_adapter = Some(&heading_adapter);
+  plugins.render.heading_adapter = Some(&render_ctx.toc);
 
   let md = parse_links(md, render_ctx);
 
@@ -323,7 +312,7 @@ pub fn markdown_to_html(
     let mut ammonia_builder = ammonia::Builder::default();
 
     ammonia_builder
-      .add_tags(["video", "button", "svg", "path"])
+      .add_tags(["video", "button", "svg", "path", "rect"])
       .add_generic_attributes(["id", "align"])
       .add_tag_attributes("button", ["data-copy"])
       .add_tag_attributes(
@@ -353,6 +342,7 @@ pub fn markdown_to_html(
           "stroke-linejoin",
         ],
       )
+      .add_tag_attributes("rect", ["x", "y", "width", "height", "fill"])
       .add_tag_attributes("video", ["src", "controls"])
       .add_allowed_classes("pre", ["highlight"])
       .add_allowed_classes("button", ["context_button"])
@@ -387,46 +377,7 @@ pub fn markdown_to_html(
     html = ammonia_builder.clean(&html).to_string();
   }
 
-  let toc = if render_options.render_toc {
-    let toc = heading_adapter.into_toc();
-
-    if toc.is_empty() {
-      None
-    } else {
-      let mut toc_content = vec![String::from(r#"<nav class="toc"><ul>"#)];
-
-      let mut current_level = 1;
-
-      for (level, heading, anchor) in toc {
-        match current_level.cmp(&level) {
-          Ordering::Equal => {}
-          Ordering::Less => {
-            toc_content.push(r#"<li><ul>"#.to_string());
-            current_level = level;
-          }
-          Ordering::Greater => {
-            toc_content.push("</ul></li>".to_string());
-            current_level = level;
-          }
-        }
-
-        toc_content.push(format!(
-          r##"<li><a href="#{anchor}" title="{heading}">{heading}</a></li>"##
-        ));
-      }
-
-      toc_content.push(String::from("</ul></nav>"));
-
-      Some(toc_content.join(""))
-    }
-  } else {
-    None
-  };
-
-  Some(Markdown {
-    html: format!(r#"<div class="{class_name} flex-1">{html}</div>"#),
-    toc,
-  })
+  Some(format!(r#"<div class="{class_name}">{html}</div>"#))
 }
 
 pub(crate) fn render_markdown_summary(
@@ -439,11 +390,9 @@ pub(crate) fn render_markdown_summary(
     MarkdownToHTMLOptions {
       summary: true,
       summary_prefer_title: false,
-      render_toc: false,
     },
   )
   .unwrap_or_default()
-  .html
 }
 
 pub(crate) fn render_markdown(render_ctx: &RenderContext, md: &str) -> String {
@@ -453,11 +402,9 @@ pub(crate) fn render_markdown(render_ctx: &RenderContext, md: &str) -> String {
     MarkdownToHTMLOptions {
       summary: false,
       summary_prefer_title: false,
-      render_toc: false,
     },
   )
   .unwrap_or_default()
-  .html
 }
 
 pub(crate) fn jsdoc_body_to_html(
@@ -472,10 +419,8 @@ pub(crate) fn jsdoc_body_to_html(
       MarkdownToHTMLOptions {
         summary,
         summary_prefer_title: false,
-        render_toc: false,
       },
     )
-    .map(|markdown| markdown.html)
   } else {
     None
   }
@@ -503,6 +448,7 @@ pub(crate) fn jsdoc_examples(
 
   if !examples.is_empty() {
     Some(SectionCtx::new(
+      ctx,
       "Examples",
       SectionContentCtx::Example(examples),
     ))
@@ -547,8 +493,6 @@ impl ExampleCtx {
 #[derive(Debug, Serialize, Clone, Default)]
 pub struct ModuleDocCtx {
   pub deprecated: Option<String>,
-  pub usages: Option<UsagesCtx>,
-  pub toc: Option<String>,
   pub sections: super::SymbolContentCtx,
 }
 
@@ -560,7 +504,7 @@ impl ModuleDocCtx {
 
     let mut sections = Vec::with_capacity(7);
 
-    let (deprecated, html, toc) = if let Some(node) = module_doc_nodes
+    let (deprecated, html) = if let Some(node) = module_doc_nodes
       .iter()
       .find(|n| n.kind == DocNodeKind::ModuleDoc)
     {
@@ -579,26 +523,11 @@ impl ModuleDocCtx {
         sections.push(examples);
       }
 
-      let (html, toc) = if let Some(markdown) =
-        node.js_doc.doc.as_ref().and_then(|doc| {
-          markdown_to_html(
-            render_ctx,
-            doc,
-            MarkdownToHTMLOptions {
-              summary: false,
-              summary_prefer_title: false,
-              render_toc: true,
-            },
-          )
-        }) {
-        (Some(markdown.html), markdown.toc)
-      } else {
-        (None, None)
-      };
+      let html = jsdoc_body_to_html(render_ctx, &node.js_doc, false);
 
-      (deprecated, html, toc)
+      (deprecated, html)
     } else {
-      (None, None, None)
+      (None, None)
     };
 
     if !short_path.is_main {
@@ -612,7 +541,8 @@ impl ModuleDocCtx {
           .map(|(title, nodes)| {
             (
               SectionHeaderCtx {
-                title,
+                title: title.clone(),
+                anchor: AnchorCtx { id: title },
                 href: None,
                 doc: None,
               },
@@ -625,8 +555,6 @@ impl ModuleDocCtx {
 
     Self {
       deprecated,
-      usages: UsagesCtx::new(render_ctx, &[]),
-      toc,
       sections: super::SymbolContentCtx {
         id: "module_doc".to_string(),
         docs: html,