feat(html): rework category panel and notes (#617)

src/html/comrak_adapters.rs

@@ -118,8 +118,9 @@ impl SyntaxHighlighterAdapter for HighlightAdapter {
       syntect::util::LinesWithEndings::from(code),
       |lines, line| {
         let regions = highlighter.highlight_line(line, &self.syntax_set)?;
+
         syntect::html::append_highlighted_html_for_styled_line(
-          &regions[..],
+          &regions,
           syntect::html::IncludeBackground::No,
           lines,
         )?;

src/html/jsdoc.rs

@@ -152,7 +152,7 @@ fn parse_links<'a>(md: &'a str, ctx: &RenderContext) -> Cow<'a, str> {
             short_path.as_resolve_kind(),
           );
           if title.is_empty() {
-            title = short_path.display_name();
+            title = short_path.display_name().to_string();
           }
         }
       }
@@ -255,20 +255,35 @@ fn match_node_value<'a>(
         if paragraph_child.data.borrow().value == NodeValue::Paragraph {
           let alert = paragraph_child.first_child().and_then(|text_child| {
             if let NodeValue::Text(text) = &text_child.data.borrow().value {
-              match text.as_str() {
-                "[!NOTE]" => Some(Alert::Note),
-                "[!TIP]" => Some(Alert::Tip),
-                "[!IMPORTANT]" => Some(Alert::Important),
-                "[!WARNING]" => Some(Alert::Warning),
-                "[!CAUTION]" => Some(Alert::Caution),
+              match text
+                .split_once(' ')
+                .map_or((text.as_str(), None), |(kind, title)| {
+                  (kind, Some(title))
+                }) {
+                ("[!NOTE]", title) => {
+                  Some((Alert::Note, title.unwrap_or("Note").to_string()))
+                }
+                ("[!TIP]", title) => {
+                  Some((Alert::Tip, title.unwrap_or("Tip").to_string()))
+                }
+                ("[!IMPORTANT]", title) => Some((
+                  Alert::Important,
+                  title.unwrap_or("Important").to_string(),
+                )),
+                ("[!WARNING]", title) => {
+                  Some((Alert::Warning, title.unwrap_or("Warning").to_string()))
+                }
+                ("[!CAUTION]", title) => {
+                  Some((Alert::Caution, title.unwrap_or("Caution").to_string()))
+                }
                 _ => None,
               }
             } else {
               None
             }
           });
 
-          if let Some(alert) = alert {
+          if let Some((alert, title)) = alert {
             let start_col = node.data.borrow().sourcepos.start;
 
             let document = arena.alloc(AstNode::new(RefCell::new(Ast::new(
@@ -293,22 +308,22 @@ fn match_node_value<'a>(
 
             let alert_title = match alert {
               Alert::Note => format!(
-                "{}Note",
+                "{}{title}",
                 include_str!("./templates/icons/info-circle.svg")
               ),
               Alert::Tip => {
-                format!("{}Tip", include_str!("./templates/icons/bulb.svg"))
+                format!("{}{title}", include_str!("./templates/icons/bulb.svg"))
               }
               Alert::Important => format!(
-                "{}Important",
+                "{}{title}",
                 include_str!("./templates/icons/warning-message.svg")
               ),
               Alert::Warning => format!(
-                "{}Warning",
+                "{}{title}",
                 include_str!("./templates/icons/warning-triangle.svg")
               ),
               Alert::Caution => format!(
-                "{}Caution",
+                "{}{title}",
                 include_str!("./templates/icons/warning-octagon.svg")
               ),
             };
@@ -746,7 +761,7 @@ mod test {
     fn resolve_usage(&self, current_resolve: UrlResolveKind) -> Option<String> {
       current_resolve
         .get_file()
-        .map(|current_file| current_file.display_name())
+        .map(|current_file| current_file.display_name().to_string())
     }
 
     fn resolve_source(&self, _location: &Location) -> Option<String> {

src/html/mod.rs

@@ -475,17 +475,16 @@ impl ShortPath {
     }
   }
 
-  pub fn display_name(&self) -> String {
+  pub fn display_name(&self) -> &str {
     if self.is_main {
-      "default".to_string()
+      "default"
     } else {
       self
         .path
         .strip_prefix('.')
         .unwrap_or(&self.path)
         .strip_prefix('/')
         .unwrap_or(&self.path)
-        .to_string()
     }
   }
 
@@ -503,7 +502,7 @@ impl Ord for ShortPath {
     other
       .is_main
       .cmp(&self.is_main)
-      .then_with(|| self.display_name().cmp(&other.display_name()))
+      .then_with(|| self.display_name().cmp(other.display_name()))
   }
 }
 

src/html/pages.rs

@@ -85,7 +85,7 @@ pub struct CategoriesPanelCtx {
 impl CategoriesPanelCtx {
   pub const TEMPLATE: &'static str = "category_panel";
 
-  pub fn new(ctx: &RenderContext) -> Option<Self> {
+  pub fn new(ctx: &RenderContext, current_path: Option<&str>) -> Option<Self> {
     match ctx.ctx.file_mode {
       FileMode::Dts => {
         let total_symbols = ctx
@@ -101,11 +101,14 @@ impl CategoriesPanelCtx {
           .doc_nodes
           .keys()
           .map(|short_path| CategoriesPanelCategoryCtx {
-            name: short_path.display_name(),
+            name: short_path.display_name().to_string(),
             href: ctx.ctx.resolve_path(
               ctx.get_current_resolve(),
               UrlResolveKind::File(short_path),
             ),
+            active: current_path.is_some_and(|current_path| {
+              current_path == short_path.display_name()
+            }),
           })
           .collect::<Vec<_>>();
 
@@ -142,6 +145,8 @@ impl CategoriesPanelCtx {
               ctx.get_current_resolve(),
               UrlResolveKind::Category(&title),
             ),
+            active: current_path
+              .is_some_and(|current_path| current_path == title),
             name: title,
           })
           .collect::<Vec<_>>();
@@ -168,6 +173,7 @@ impl CategoriesPanelCtx {
 pub struct CategoriesPanelCategoryCtx {
   pub name: String,
   pub href: String,
+  pub active: bool,
 }
 
 #[derive(Debug, Serialize)]
@@ -241,16 +247,16 @@ impl IndexCtx {
 
             let title = short_path.display_name();
 
-            let anchor = render_ctx.toc.anchorize(&title);
-            render_ctx.toc.add_entry(1, &title, &anchor);
+            let anchor = render_ctx.toc.anchorize(title);
+            render_ctx.toc.add_entry(1, title, &anchor);
 
             util::SectionCtx {
               header: SectionHeaderCtx {
                 href: Some(ctx.resolve_path(
                   UrlResolveKind::Root,
                   short_path.as_resolve_kind(),
                 )),
-                title,
+                title: title.to_string(),
                 anchor: AnchorCtx { id: anchor },
                 doc,
               },
@@ -320,7 +326,12 @@ impl IndexCtx {
 
     let dts_mode = matches!(ctx.file_mode, FileMode::SingleDts | FileMode::Dts);
 
-    let categories_panel = CategoriesPanelCtx::new(&render_ctx);
+    let categories_panel = CategoriesPanelCtx::new(
+      &render_ctx,
+      short_path
+        .as_ref()
+        .map(|short_path| short_path.display_name()),
+    );
     let usage = dts_mode.then(|| UsagesCtx::new(&render_ctx, &[])).flatten();
 
     let toc_ctx = util::ToCCtx::new(
@@ -382,7 +393,7 @@ impl IndexCtx {
 
     let breadcrumbs_ctx = render_ctx.get_breadcrumbs();
 
-    let categories_panel = CategoriesPanelCtx::new(&render_ctx);
+    let categories_panel = CategoriesPanelCtx::new(&render_ctx, Some(name));
     let usage = UsagesCtx::new(&render_ctx, &[]);
 
     let toc_ctx = util::ToCCtx::new(
@@ -445,7 +456,7 @@ impl AllSymbolsCtx {
       ctx.disable_search,
     );
 
-    let categories_panel = CategoriesPanelCtx::new(&render_ctx);
+    let categories_panel = CategoriesPanelCtx::new(&render_ctx, None);
 
     AllSymbolsCtx {
       html_head_ctx,
@@ -743,7 +754,14 @@ pub fn render_symbol_page(
   let symbol_group_ctx =
     SymbolGroupCtx::new(&render_ctx, doc_nodes, namespaced_name);
 
-  let categories_panel = CategoriesPanelCtx::new(&render_ctx);
+  let categories_panel = CategoriesPanelCtx::new(
+    &render_ctx,
+    Some(
+      render_ctx
+        .category
+        .unwrap_or_else(|| short_path.display_name()),
+    ),
+  );
 
   let toc_nodes = (!matches!(
     render_ctx.ctx.file_mode,

src/html/render_context.rs

@@ -20,7 +20,7 @@ pub struct RenderContext<'ctx> {
   /// A vector of parts of the current namespace, eg. `vec!["Deno", "errors"]`.
   namespace_parts: Rc<[String]>,
   /// Only some when in `FileMode::SingleDts` and using categories
-  category: Option<&'ctx str>,
+  pub category: Option<&'ctx str>,
   pub toc: crate::html::comrak_adapters::HeadingToCAdapter,
 }
 
@@ -227,7 +227,7 @@ impl<'ctx> RenderContext<'ctx> {
               is_first_symbol: false,
             },
             BreadcrumbCtx {
-              name: file.display_name(),
+              name: file.display_name().to_string(),
               href: "".to_string(),
               is_symbol: false,
               is_first_symbol: false,
@@ -247,7 +247,7 @@ impl<'ctx> RenderContext<'ctx> {
 
         if !file.is_main {
           parts.push(BreadcrumbCtx {
-            name: file.display_name(),
+            name: file.display_name().to_string(),
             href: self
               .ctx
               .resolve_path(self.current_resolve, UrlResolveKind::File(file)),

src/html/templates/category_panel.hbs

@@ -2,7 +2,7 @@
   <div id="categoryPanel">
     <ul>
       {{~#each categories~}}
-        <li><a href="{{this.href}}" title="{{this.name}}">{{this.name}}</a></li>
+        <li{{#if this.active}} class="active"{{/if}}><a href="{{this.href}}" title="{{this.name}}">{{this.name}}</a></li>
       {{~/each~}}
 
       <li>

src/html/templates/pages/page.css

@@ -2,14 +2,12 @@
 @tailwind utilities;
 
 .ddoc {
-  /* keep in sync with #topnav further down */
-  @apply flex h-screen items-start gap-6 p-4 lg:p-2;
-
-  &:not(:has(#categoryPanel)) {
-    @apply lg:pt-4;
-  }
+  /* keep spacing in sync with #topnav in various places further down */
+  @apply flex min-h-fit items-start gap-6 p-4;
 
   &:has(#categoryPanel) {
+    @apply lg:p-2;
+
     & > div:not(#categoryPanel) {
       @apply lg:pt-4;
     }
@@ -30,13 +28,17 @@
 }
 
 #categoryPanel {
-  @apply max-lg:hidden lg:flex lg:flex-col -mt-0 pt-0 w-[250px] flex-shrink-0 top-0 sticky max-h-screen h-fit box-border;
+  @apply max-lg:hidden -mt-0 pt-0 w-[250px] flex-shrink-0 top-0 sticky h-screen box-border;
+
+  > ul {
+    @apply max-h-full overflow-y-auto;
+  }
 }
 
 #content {
   @apply mt-4;
 
-  & > main {
+  > main {
     @apply min-w-0 col-span-full pb-0 md:pb-8 lg:pb-12 flex flex-col gap-3 flex-grow;
   }
 
@@ -46,7 +48,7 @@
 }
 
 #topnav {
-  @apply -ml-4 pl-4 lg:-ml-2 lg:pl-2;
+  @apply -ml-4 pl-4;
 }
 
 #content, #topnav > div {