fix(html): always show example content, enable ammonia by default, and dont collapse newlines in jsdoc (#654)

Author: crowlKats

Cargo.toml

@@ -75,9 +75,9 @@ pretty_assertions = "1.4.0"
 insta = { version = "1.39.0", features = ["json"] }
 
 [features]
-default = ["html", "rust", "ammonia", "tree-sitter"]
+default = ["html", "rust", "tree-sitter"]
 rust = []
-html = ["html-escape", "comrak", "handlebars"]
+html = ["html-escape", "comrak", "handlebars", "ammonia"]
 tree-sitter = [
   "tree-sitter-highlight",
   "tree-sitter-javascript",

src/html/comrak_adapters.rs

@@ -368,6 +368,5 @@ impl HeadingAdapter for HeadingToCAdapter {
   }
 }
 
-#[cfg(feature = "ammonia")]
 pub type URLRewriter =
   Arc<dyn (Fn(Option<&crate::html::ShortPath>, &str) -> String) + Send + Sync>;

src/html/jsdoc.rs

@@ -1,6 +1,5 @@
 use super::render_context::RenderContext;
 use super::util::*;
-#[cfg(feature = "ammonia")]
 use crate::html::comrak_adapters::URLRewriter;
 use crate::html::ShortPath;
 use crate::js_doc::JsDoc;
@@ -28,7 +27,6 @@ lazy_static! {
     regex::Regex::new(r"^\[(\S+)\](?:\.(\S+)|\s|)$").unwrap();
 }
 
-#[cfg(feature = "ammonia")]
 lazy_static! {
   static ref AMMONIA: ammonia::Builder<'static> = {
     let mut ammonia_builder = ammonia::Builder::default();
@@ -94,7 +92,6 @@ lazy_static! {
   };
 }
 
-#[cfg(feature = "ammonia")]
 thread_local! {
   static CURRENT_FILE: RefCell<Option<Option<ShortPath>>> = const { RefCell::new(None) };
   static URL_REWRITER: RefCell<Option<Option<URLRewriter>>> = const { RefCell::new(None) };
@@ -222,10 +219,8 @@ fn split_markdown_title(md: &str) -> (Option<&str>, Option<&str>) {
   }
 }
 
-#[cfg(feature = "ammonia")]
 struct AmmoniaRelativeUrlEvaluator();
 
-#[cfg(feature = "ammonia")]
 impl<'b> ammonia::UrlRelativeEvaluate<'b> for AmmoniaRelativeUrlEvaluator {
   fn evaluate<'a>(&self, url: &'a str) -> Option<Cow<'a, str>> {
     URL_REWRITER.with(|url_rewriter| {
@@ -412,6 +407,7 @@ fn walk_node_title<'a>(node: &'a AstNode<'a>) {
         | NodeValue::Escaped
         | NodeValue::WikiLink(_)
         | NodeValue::Underline
+        | NodeValue::SoftBreak
     ) {
       walk_node_title(child);
     } else {
@@ -490,14 +486,7 @@ pub fn markdown_to_html(
   options.extension.table = true;
   options.extension.tagfilter = true;
   options.extension.tasklist = true;
-  #[cfg(not(feature = "ammonia"))]
-  {
-    options.render.escape = true;
-  }
-  #[cfg(feature = "ammonia")]
-  {
-    options.render.unsafe_ = true; // its fine because we run ammonia afterwards
-  }
+  options.render.unsafe_ = true; // its fine because we run ammonia afterwards
 
   let mut plugins = comrak::Plugins::default();
 
@@ -535,26 +524,18 @@ pub fn markdown_to_html(
     }
   };
 
-  #[cfg(feature = "ammonia")]
-  {
-    CURRENT_FILE
-      .set(Some(render_ctx.get_current_resolve().get_file().cloned()));
-    URL_REWRITER.set(Some(render_ctx.ctx.url_rewriter.clone()));
+  CURRENT_FILE.set(Some(render_ctx.get_current_resolve().get_file().cloned()));
+  URL_REWRITER.set(Some(render_ctx.ctx.url_rewriter.clone()));
 
-    let html = Some(format!(
-      r#"<div class="{class_name}">{}</div>"#,
-      AMMONIA.clean(&html)
-    ));
+  let html = Some(format!(
+    r#"<div class="{class_name}">{}</div>"#,
+    AMMONIA.clean(&html)
+  ));
 
-    CURRENT_FILE.set(None);
-    URL_REWRITER.set(None);
+  CURRENT_FILE.set(None);
+  URL_REWRITER.set(None);
 
-    html
-  }
-  #[cfg(not(feature = "ammonia"))]
-  {
-    Some(format!(r#"<div class="{class_name}">{html}</div>"#))
-  }
+  html
 }
 
 pub(crate) fn render_markdown(

src/html/mod.rs

@@ -264,7 +264,6 @@ pub struct GenerateCtx {
   pub common_ancestor: Option<PathBuf>,
   pub doc_nodes: IndexMap<Rc<ShortPath>, Vec<DocNodeWithContext>>,
   pub highlight_adapter: comrak_adapters::HighlightAdapter,
-  #[cfg(feature = "ammonia")]
   pub url_rewriter: Option<comrak_adapters::URLRewriter>,
   pub href_resolver: Rc<dyn HrefResolver>,
   pub usage_composer: Option<UsageComposer>,
@@ -370,7 +369,6 @@ impl GenerateCtx {
       common_ancestor,
       doc_nodes,
       highlight_adapter: setup_highlighter(false),
-      #[cfg(feature = "ammonia")]
       url_rewriter: None,
       href_resolver: options.href_resolver,
       usage_composer: options.usage_composer,

src/html/templates/example.hbs

@@ -1,13 +1,10 @@
-<div class="anchorable example">
+<div class="anchorable">
   {{~> anchor anchor ~}}
 
-  <details id="{{id}}" open>
-    <summary>
-      <div>&#x25B6;</div>
-      {{{~markdown_title~}}} {{! markdown rendering }}
-    </summary>
-    <div>
-      {{{~markdown_body~}}} {{! markdown rendering }}
-    </div>
-  </details>
+  <h3 class="example-header">
+    {{{~markdown_title~}}} {{! markdown rendering }}
+  </h3>
+  <div>
+    {{{~markdown_body~}}} {{! markdown rendering }}
+  </div>
 </div>

src/html/templates/section.hbs

@@ -22,6 +22,10 @@
       <div class="space-y-8">
         {{~#each content.content~}}
           {{~> (lookup ../content "kind") this ~}}
+
+          {{~#if (and (eq (lookup ../content "kind") "example") (not @last))~}}
+            <div class="border-b border-gray-300"></div>
+          {{~/if~}}
         {{~/each~}}
       </div>
     {{~/if~}}

src/html/templates/styles.css

@@ -167,19 +167,8 @@ a {
   }
 }
 
-.example details {
-  summary {
-    @apply list-none flex items-center gap-2 py-2 rounded-lg w-full leading-6
-      cursor-pointer;
-
-    > div:first-child {
-      @apply text-stone-600 select-none;
-    }
-  }
-
-  &[open] summary > div:first-child {
-    @apply rotate-90;
-  }
+.example-header {
+  @apply font-bold text-lg mb-3;
 }
 
 .toc {

src/html/templates/styles.gen.css

@@ -34,7 +34,8 @@ expression: "files.get(\"./index.html\").unwrap()"
 </nav>
 <div id="searchResults"></div><div id="content">
     <main><section >
-  <div class="space-y-2 flex-1 "><div class="space-y-7" id="module_doc"><div class="markdown"><p>Some docs</p>
+  <div class="space-y-2 flex-1 "><div class="space-y-7" id="module_doc"><div class="markdown"><p>Some docs
+with a line break</p>
 <div class="alert alert-note"><div><svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
   <path stroke="none" d="M0 0h24v24H0z" fill="none"></path>
   <path d="M3 12a9 9 0 1 0 18 0a9 9 0 0 0 -18 0"></path>

tests/snapshots/html_test__html_doc_files_rewrite-2.snap

@@ -3,5 +3,5 @@ source: tests/html_test.rs
 expression: "files.get(\"search_index.js\").unwrap()"
 ---
 (function () {
-  window.DENO_DOC_SEARCH_INDEX = {"nodes":[{"kind":[{"char":"c","kind":"Class","title":"Class"}],"name":"A","file":".","doc":"","url":"././~/A.html","deprecated":false},{"kind":[{"char":"c","kind":"Class","title":"Class"}],"name":"B","file":".","doc":"","url":"././~/B.html","deprecated":false},{"kind":[{"char":"c","kind":"Class","title":"Class"}],"name":"Bar","file":".","doc":"> Some quote in bar docs\n> This quote part is ignored\n> when getting the title of this doc\n\nBar docs","url":"././~/Bar.html","deprecated":false},{"kind":[{"char":"T","kind":"TypeAlias","title":"Type Alias"}],"name":"Baz","file":".","doc":"","url":"././~/Baz.html","deprecated":false},{"kind":[{"char":"p","kind":"Property","title":"Property"}],"name":"Baz.foo","file":".","doc":"","url":"././~/Baz.foo.html","deprecated":false},{"kind":[{"char":"c","kind":"Class","title":"Class"}],"name":"Foo","file":".","doc":"some Foo docs {@linkcode Bar}","url":"././~/Foo.html","deprecated":false},{"kind":[{"char":"m","kind":"Method","title":"Method"}],"name":"Foo.prototype.test","file":".","doc":"","url":"././~/Foo.prototype.test.html","deprecated":false},{"kind":[{"char":"p","kind":"Property","title":"Property"}],"name":"Foo.bar","file":".","doc":"","url":"././~/Foo.bar.html","deprecated":false},{"kind":[{"char":"p","kind":"Property","title":"Property"}],"name":"Foo.prototype.foo","file":".","doc":"","url":"././~/Foo.prototype.foo.html","deprecated":false},{"kind":[{"char":"p","kind":"Property","title":"Property"}],"name":"Foo.prototype.\"&gt;&lt;img src=x onerror=alert(1)&gt;","file":".","doc":"","url":"././~/Foo.prototype.\"><img src=x onerror=alert(1)>.html","deprecated":false},{"kind":[{"char":"c","kind":"Class","title":"Class"}],"name":"Foobar","file":".","doc":"```ts\n// This code block is ignored when getting the title of this doc\nconst foobar = new Foobar();\n```\n\nFoobar docs\n","url":"././~/Foobar.html","deprecated":false},{"kind":[{"char":"I","kind":"Interface","title":"Interface"}],"name":"Hello","file":".","doc":"","url":"././~/Hello.html","deprecated":false},{"kind":[{"char":"p","kind":"Property","title":"Property"}],"name":"Hello.world","file":".","doc":"","url":"././~/Hello.world.html","deprecated":false},{"kind":[{"char":"f","kind":"Function","title":"Function"}],"name":"c","file":".","doc":"","url":"././~/c.html","deprecated":false},{"kind":[{"char":"f","kind":"Function","title":"Function"}],"name":"d","file":".","doc":"","url":"././~/d.html","deprecated":false},{"kind":[{"char":"f","kind":"Function","title":"Function"},{"char":"f","kind":"Function","title":"Function"},{"char":"f","kind":"Function","title":"Function"}],"name":"qaz","file":".","doc":"","url":"././~/qaz.html","deprecated":false},{"kind":[{"char":"v","kind":"Variable","title":"Variable"}],"name":"default","file":"foo","doc":"The default export item.\n\nThis item reproduces the issue reported in {@link https://github.com/jsr-io/jsr/issues/459}","url":"./foo/~/default.html","deprecated":false},{"kind":[{"char":"f","kind":"Function","title":"Function"}],"name":"x","file":"foo","doc":"","url":"./foo/~/x.html","deprecated":false}]};
+  window.DENO_DOC_SEARCH_INDEX = {"nodes":[{"kind":[{"char":"c","kind":"Class","title":"Class"}],"name":"A","file":".","doc":"","url":"././~/A.html","deprecated":false},{"kind":[{"char":"c","kind":"Class","title":"Class"}],"name":"B","file":".","doc":"","url":"././~/B.html","deprecated":false},{"kind":[{"char":"c","kind":"Class","title":"Class"}],"name":"Bar","file":".","doc":"> Some quote in bar docs\n> This quote part is ignored\n> when getting the title of this doc\n\nBar docs","url":"././~/Bar.html","deprecated":false},{"kind":[{"char":"T","kind":"TypeAlias","title":"Type Alias"}],"name":"Baz","file":".","doc":"","url":"././~/Baz.html","deprecated":false},{"kind":[{"char":"p","kind":"Property","title":"Property"}],"name":"Baz.foo","file":".","doc":"","url":"././~/Baz.foo.html","deprecated":false},{"kind":[{"char":"c","kind":"Class","title":"Class"}],"name":"Foo","file":".","doc":"some Foo docs {@linkcode Bar}\n","url":"././~/Foo.html","deprecated":false},{"kind":[{"char":"m","kind":"Method","title":"Method"}],"name":"Foo.prototype.test","file":".","doc":"","url":"././~/Foo.prototype.test.html","deprecated":false},{"kind":[{"char":"p","kind":"Property","title":"Property"}],"name":"Foo.bar","file":".","doc":"","url":"././~/Foo.bar.html","deprecated":false},{"kind":[{"char":"p","kind":"Property","title":"Property"}],"name":"Foo.prototype.foo","file":".","doc":"","url":"././~/Foo.prototype.foo.html","deprecated":false},{"kind":[{"char":"p","kind":"Property","title":"Property"}],"name":"Foo.prototype.\"&gt;&lt;img src=x onerror=alert(1)&gt;","file":".","doc":"","url":"././~/Foo.prototype.\"><img src=x onerror=alert(1)>.html","deprecated":false},{"kind":[{"char":"c","kind":"Class","title":"Class"}],"name":"Foobar","file":".","doc":"```ts\n// This code block is ignored when getting the title of this doc\nconst foobar = new Foobar();\n```\n\nFoobar docs\n","url":"././~/Foobar.html","deprecated":false},{"kind":[{"char":"I","kind":"Interface","title":"Interface"}],"name":"Hello","file":".","doc":"","url":"././~/Hello.html","deprecated":false},{"kind":[{"char":"p","kind":"Property","title":"Property"}],"name":"Hello.world","file":".","doc":"","url":"././~/Hello.world.html","deprecated":false},{"kind":[{"char":"f","kind":"Function","title":"Function"}],"name":"c","file":".","doc":"","url":"././~/c.html","deprecated":false},{"kind":[{"char":"f","kind":"Function","title":"Function"}],"name":"d","file":".","doc":"","url":"././~/d.html","deprecated":false},{"kind":[{"char":"f","kind":"Function","title":"Function"},{"char":"f","kind":"Function","title":"Function"},{"char":"f","kind":"Function","title":"Function"}],"name":"qaz","file":".","doc":"","url":"././~/qaz.html","deprecated":false},{"kind":[{"char":"v","kind":"Variable","title":"Variable"}],"name":"default","file":"foo","doc":"The default export item.\n\nThis item reproduces the issue reported in {@link https://github.com/jsr-io/jsr/issues/459}","url":"./foo/~/default.html","deprecated":false},{"kind":[{"char":"f","kind":"Function","title":"Function"}],"name":"x","file":"foo","doc":"","url":"./foo/~/x.html","deprecated":false}]};
 })()