diff --git a/src/html/comrak_adapters.rs b/src/html/comrak_adapters.rs
index 96fcaf95..4d4a1fd0 100644
--- a/src/html/comrak_adapters.rs
+++ b/src/html/comrak_adapters.rs
@@ -75,7 +75,7 @@ impl HighlightAdapter {
     write!(
       output,
       r#"<button class="context_button" data-copy="{}">{}</button>"#,
-      html_escape::encode_safe(source),
+      html_escape::encode_double_quoted_attribute(source),
       include_str!("./templates/icons/copy.svg")
     )?;
     write!(output, "<code>")
diff --git a/src/html/parameters.rs b/src/html/parameters.rs
index fe829ccb..26331114 100644
--- a/src/html/parameters.rs
+++ b/src/html/parameters.rs
@@ -62,7 +62,7 @@ pub(crate) fn param_name(param: &ParamDef, i: usize) -> (String, String) {
     ),
     ParamPatternDef::Assign { left, .. } => param_name(left, i),
     ParamPatternDef::Identifier { name, .. } => {
-      (html_escape::encode_safe(name).into_owned(), name.clone())
+      (html_escape::encode_text(name).into_owned(), name.clone())
     }
     ParamPatternDef::Rest { arg } => (
       format!("<span>...{}</span>", param_name(arg, i).0),
diff --git a/src/html/search.rs b/src/html/search.rs
index a96418a0..a3f47943 100644
--- a/src/html/search.rs
+++ b/src/html/search.rs
@@ -37,12 +37,12 @@ fn doc_node_into_search_index_nodes(
     .ns_qualifiers
     .is_empty()
   {
-    html_escape::encode_safe(name).into_owned()
+    html_escape::encode_text(name).into_owned()
   } else {
     format!(
       "{}.{}",
       doc_nodes[0].ns_qualifiers.join("."),
-      html_escape::encode_safe(name)
+      html_escape::encode_text(name)
     )
   };
 
@@ -55,7 +55,7 @@ fn doc_node_into_search_index_nodes(
       .map(|main_entrypoint| main_entrypoint != &location_url)
       .unwrap_or(true)
     {
-      html_escape::encode_safe(&ctx.url_to_short_path(&location_url).to_name())
+      html_escape::encode_text(&ctx.url_to_short_path(&location_url).to_name())
         .into_owned()
     } else {
       String::new()
@@ -64,7 +64,10 @@ fn doc_node_into_search_index_nodes(
     return vec![SearchIndexNode {
       kind: kinds,
       name,
-      file: html_escape::encode_safe(doc_nodes[0].origin.as_str()).into_owned(),
+      file: html_escape::encode_double_quoted_attribute(
+        doc_nodes[0].origin.as_str(),
+      )
+      .into_owned(),
       location,
       declaration_kind: doc_nodes[0].declaration_kind,
       deprecated,
@@ -83,7 +86,7 @@ fn doc_node_into_search_index_nodes(
     .map(|main_entrypoint| main_entrypoint != &location_url)
     .unwrap_or(true)
   {
-    html_escape::encode_safe(&ctx.url_to_short_path(&location_url).to_name())
+    html_escape::encode_text(&ctx.url_to_short_path(&location_url).to_name())
       .into_owned()
   } else {
     String::new()
@@ -92,7 +95,10 @@ fn doc_node_into_search_index_nodes(
   nodes.push(SearchIndexNode {
     kind: kinds,
     name,
-    file: html_escape::encode_safe(doc_nodes[0].origin.as_str()).into_owned(),
+    file: html_escape::encode_double_quoted_attribute(
+      doc_nodes[0].origin.as_str(),
+    )
+    .into_owned(),
     location,
     declaration_kind: doc_nodes[0].declaration_kind,
     deprecated,
@@ -124,19 +130,19 @@ fn doc_node_into_search_index_nodes(
       .map(|main_entrypoint| main_entrypoint != &location_url)
       .unwrap_or(true)
     {
-      html_escape::encode_safe(&ctx.url_to_short_path(&location_url).to_name())
+      html_escape::encode_text(&ctx.url_to_short_path(&location_url).to_name())
         .into_owned()
     } else {
       String::new()
     };
 
     let name = if ns_qualifiers_.is_empty() {
-      html_escape::encode_safe(el_name).into_owned()
+      html_escape::encode_text(el_name).into_owned()
     } else {
       format!(
         "{}.{}",
         ns_qualifiers_.join("."),
-        html_escape::encode_safe(el_name)
+        html_escape::encode_text(el_name)
       )
     };
 
@@ -145,7 +151,10 @@ fn doc_node_into_search_index_nodes(
     nodes.push(SearchIndexNode {
       kind: kinds,
       name,
-      file: html_escape::encode_safe(doc_nodes[0].origin.as_str()).into_owned(),
+      file: html_escape::encode_double_quoted_attribute(
+        doc_nodes[0].origin.as_str(),
+      )
+      .into_owned(),
       location,
       declaration_kind: el_nodes[0].declaration_kind,
       deprecated,
diff --git a/src/html/symbols/class.rs b/src/html/symbols/class.rs
index b927119d..fcb048e8 100644
--- a/src/html/symbols/class.rs
+++ b/src/html/symbols/class.rs
@@ -128,7 +128,7 @@ fn render_constructors(
       DocEntryCtx::new(
         ctx,
         &id,
-        &html_escape::encode_safe(&name),
+        &html_escape::encode_text(&name),
         None,
         &format!("({params})"),
         HashSet::from([Tag::New]),
@@ -380,7 +380,7 @@ fn render_class_accessor(
   DocEntryCtx::new(
     ctx,
     &id,
-    &html_escape::encode_safe(&name),
+    &html_escape::encode_text(&name),
     ctx.lookup_symbol_href(&qualify_drilldown_name(
       class_name,
       name,
@@ -419,7 +419,7 @@ fn render_class_method(
   Some(DocEntryCtx::new(
     ctx,
     &id,
-    &html_escape::encode_safe(&method.name),
+    &html_escape::encode_text(&method.name),
     ctx.lookup_symbol_href(&qualify_drilldown_name(
       class_name,
       &method.name,
@@ -462,7 +462,7 @@ fn render_class_property(
   DocEntryCtx::new(
     ctx,
     &id,
-    &html_escape::encode_safe(&property.name),
+    &html_escape::encode_text(&property.name),
     ctx.lookup_symbol_href(&qualify_drilldown_name(
       class_name,
       &property.name,
diff --git a/src/html/symbols/enum.rs b/src/html/symbols/enum.rs
index d86d782e..17464c68 100644
--- a/src/html/symbols/enum.rs
+++ b/src/html/symbols/enum.rs
@@ -24,7 +24,7 @@ pub(crate) fn render_enum(
       DocEntryCtx::new(
         render_ctx,
         &id,
-        &html_escape::encode_safe(&member.name),
+        &html_escape::encode_text(&member.name),
         None,
         &member
           .init
diff --git a/src/html/symbols/interface.rs b/src/html/symbols/interface.rs
index 43b82014..8138dad9 100644
--- a/src/html/symbols/interface.rs
+++ b/src/html/symbols/interface.rs
@@ -161,7 +161,7 @@ fn render_properties(
           if let crate::js_doc::JsDocTag::Default { value, .. } = tag {
             Some(format!(
               r#"<span><span class="font-normal"> = </span>{}</span>"#,
-              html_escape::encode_safe(value)
+              html_escape::encode_text(value)
             ))
           } else {
             None
@@ -187,9 +187,9 @@ fn render_properties(
         ctx,
         &id,
         &if property.computed {
-          format!("[{}]", html_escape::encode_safe(&property.name))
+          format!("[{}]", html_escape::encode_text(&property.name))
         } else {
-          html_escape::encode_safe(&property.name).into_owned()
+          html_escape::encode_text(&property.name).into_owned()
         },
         ctx.lookup_symbol_href(&qualify_drilldown_name(
           interface_name,
@@ -228,9 +228,9 @@ fn render_methods(
       let name = if method.name == "new" {
         "<span>new</span>".to_string()
       } else if method.computed {
-        format!("[{}]", html_escape::encode_safe(&method.name))
+        format!("[{}]", html_escape::encode_text(&method.name))
       } else {
-        html_escape::encode_safe(&method.name).into_owned()
+        html_escape::encode_text(&method.name).into_owned()
       };
 
       let return_type = method
diff --git a/src/html/symbols/mod.rs b/src/html/symbols/mod.rs
index 35d91b7a..9773020d 100644
--- a/src/html/symbols/mod.rs
+++ b/src/html/symbols/mod.rs
@@ -198,7 +198,7 @@ impl DocBlockSubtitleCtx {
       if let Some(extends) = class_def.extends.as_ref() {
         class_extends = Some(DocBlockClassSubtitleExtendsCtx {
           href: ctx.lookup_symbol_href(extends),
-          symbol: html_escape::encode_safe(extends).into_owned(),
+          symbol: html_escape::encode_text(extends).into_owned(),
           type_args: super::types::type_arguments(
             ctx,
             &class_def.super_type_params,
diff --git a/src/html/types.rs b/src/html/types.rs
index 6a3f97a8..ba659c51 100644
--- a/src/html/types.rs
+++ b/src/html/types.rs
@@ -23,7 +23,7 @@ pub(crate) fn render_type_def(
   def: &crate::ts_type::TsTypeDef,
 ) -> String {
   let Some(kind) = &def.kind else {
-    return html_escape::encode_safe(&def.repr).to_string();
+    return html_escape::encode_text(&def.repr).to_string();
   };
 
   match kind {
@@ -37,7 +37,7 @@ pub(crate) fn render_type_def(
       {
         format!(
           r#"<a href="{}" class="link">{keyword}</a>"#,
-          html_escape::encode_safe(&href),
+          html_escape::encode_double_quoted_attribute(&href),
         )
       } else {
         format!("<span>{keyword}</span>")
@@ -50,10 +50,10 @@ pub(crate) fn render_type_def(
         LiteralDefKind::Number
         | LiteralDefKind::BigInt
         | LiteralDefKind::Boolean => {
-          format!("<span>{}</span>", html_escape::encode_safe(&def.repr))
+          format!("<span>{}</span>", html_escape::encode_text(&def.repr))
         }
         LiteralDefKind::String => {
-          format!("<span>{:?}</span>", html_escape::encode_safe(&def.repr))
+          format!("<span>{:?}</span>", html_escape::encode_text(&def.repr))
         }
         LiteralDefKind::Template => {
           if let Some(types) = &lit.ts_types {
@@ -65,7 +65,7 @@ pub(crate) fn render_type_def(
                 .as_ref()
                 .is_some_and(|literal| literal.string.is_some())
               {
-                html_escape::encode_safe(&ts_type.repr).into_owned()
+                html_escape::encode_text(&ts_type.repr).into_owned()
               } else {
                 format!("${{{}}}", render_type_def(ctx, ts_type))
               });
@@ -73,7 +73,7 @@ pub(crate) fn render_type_def(
 
             format!("<span>`{out}`</span>")
           } else {
-            format!("<span>`{}`</span>", html_escape::encode_safe(&def.repr))
+            format!("<span>`{}`</span>", html_escape::encode_text(&def.repr))
           }
         }
       }
@@ -93,13 +93,13 @@ pub(crate) fn render_type_def(
       let name = if let Some(href) = href {
         format!(
           r#"<a href="{}" class="link">{}</a>"#,
-          html_escape::encode_safe(&href),
-          html_escape::encode_safe(&type_ref.type_name)
+          html_escape::encode_double_quoted_attribute(&href),
+          html_escape::encode_text(&type_ref.type_name)
         )
       } else {
         format!(
           r#"<span>{}</span>"#,
-          html_escape::encode_safe(&type_ref.type_name)
+          html_escape::encode_text(&type_ref.type_name)
         )
       };
 
@@ -149,11 +149,11 @@ pub(crate) fn render_type_def(
       if let Some(href) = ctx.lookup_symbol_href(query) {
         format!(
           r#"<a href="{}" class="link">{}</a>"#,
-          html_escape::encode_safe(&href),
-          html_escape::encode_safe(query),
+          html_escape::encode_double_quoted_attribute(&href),
+          html_escape::encode_text(query),
         )
       } else {
-        format!("<span>{}</span>", html_escape::encode_safe(query))
+        format!("<span>{}</span>", html_escape::encode_text(query))
       }
     }
     TsTypeDefKind::This => "<span>this</span>".to_string(),
@@ -299,9 +299,9 @@ pub(crate) fn render_type_def(
           .unwrap_or_default();
 
         let name = if property.computed {
-          format!("[{}]", html_escape::encode_safe(&property.name))
+          format!("[{}]", html_escape::encode_text(&property.name))
         } else {
-          html_escape::encode_safe(&property.name).to_string()
+          html_escape::encode_text(&property.name).to_string()
         };
 
         let optional = property.optional.then_some("?").unwrap_or_default();
@@ -364,7 +364,7 @@ pub(crate) fn render_type_def(
       let param_type = if let crate::ts_type::ThisOrIdent::Identifier { name } =
         &type_predicate.param
       {
-        html_escape::encode_safe(name).to_string()
+        html_escape::encode_text(name).to_string()
       } else {
         "<span>this</span>".to_string()
       };
@@ -384,7 +384,7 @@ pub(crate) fn render_type_def(
         .qualifier
         .as_ref()
         .map(|qualifier| {
-          format!("<span>.{}</span>", html_escape::encode_safe(qualifier))
+          format!("<span>.{}</span>", html_escape::encode_text(qualifier))
         })
         .unwrap_or_default();
 
@@ -396,7 +396,7 @@ pub(crate) fn render_type_def(
 
       format!(
         r#"<span>import</span>("{}"){qualifier}{type_arguments}"#,
-        html_escape::encode_safe(&import_type.specifier),
+        html_escape::encode_text(&import_type.specifier),
       )
     }
   }
@@ -577,7 +577,7 @@ pub(crate) fn render_type_params(
     let content = DocEntryCtx::new(
       ctx,
       &id,
-      &html_escape::encode_safe(&type_param.name),
+      &html_escape::encode_text(&type_param.name),
       None,
       &format!("{constraint}{default}"),
       HashSet::new(),
diff --git a/src/html/usage.rs b/src/html/usage.rs
index f9a318be..f8836c2b 100644
--- a/src/html/usage.rs
+++ b/src/html/usage.rs
@@ -35,7 +35,10 @@ pub fn usage_to_md(
     let is_default = doc_nodes[0].name == "default";
 
     let import_symbol = if is_default && doc_nodes[0].get_name() == "default" {
-      file.to_name()
+      file
+        .to_name()
+        .replace('-', "_")
+        .replace(|c: char| c.is_ascii_alphanumeric(), "")
     } else {
       parts[0].to_string()
     };
@@ -69,13 +72,13 @@ pub fn usage_to_md(
       format!(
         r#"import {}{} from "{url}";"#,
         if is_type { "type " } else { "" },
-        html_escape::encode_safe(&import_symbol),
+        html_escape::encode_text(&import_symbol),
       )
     } else {
       format!(
         r#"import {{ {}{} }} from "{url}";"#,
         if is_type { "type " } else { "" },
-        html_escape::encode_safe(&import_symbol),
+        html_escape::encode_text(&import_symbol),
       )
     };
 
@@ -83,7 +86,7 @@ pub fn usage_to_md(
       usage_statement.push_str(&format!(
         "\n{} {{ {} }} = {local_var};",
         if is_type { "type" } else { "const" },
-        html_escape::encode_safe(usage_symbol),
+        html_escape::encode_text(usage_symbol),
       ));
     }
 
diff --git a/tests/testdata/symbol_group-syntect.json b/tests/testdata/symbol_group-syntect.json
index 494bf2cd..10620375 100644
--- a/tests/testdata/symbol_group-syntect.json
+++ b/tests/testdata/symbol_group-syntect.json
@@ -272,7 +272,7 @@
                       "content": [
                         {
                           "id": "property_&quot;&gt;&lt;img src=x onerror=alert(1)&gt;",
-                          "name": "&quot;&gt;&lt;img src=x onerror=alert(1)&gt;",
+                          "name": "\"&gt;&lt;img src=x onerror=alert(1)&gt;",
                           "name_href": "../././~/Foo.prototype.\"><img src=x onerror=alert(1)>.html",
                           "content": "<span>: <span>number</span></span>",
                           "anchor": {
diff --git a/tests/testdata/symbol_group-tree-sitter.json b/tests/testdata/symbol_group-tree-sitter.json
index 9737ddf8..73ad88d9 100644
--- a/tests/testdata/symbol_group-tree-sitter.json
+++ b/tests/testdata/symbol_group-tree-sitter.json
@@ -272,7 +272,7 @@
                       "content": [
                         {
                           "id": "property_&quot;&gt;&lt;img src=x onerror=alert(1)&gt;",
-                          "name": "&quot;&gt;&lt;img src=x onerror=alert(1)&gt;",
+                          "name": "\"&gt;&lt;img src=x onerror=alert(1)&gt;",
                           "name_href": "../././~/Foo.prototype.\"><img src=x onerror=alert(1)>.html",
                           "content": "<span>: <span>number</span></span>",
                           "anchor": {
diff --git a/tests/testdata/symbol_group.json b/tests/testdata/symbol_group.json
index 823d8a5a..169c77c8 100644
--- a/tests/testdata/symbol_group.json
+++ b/tests/testdata/symbol_group.json
@@ -272,7 +272,7 @@
                       "content": [
                         {
                           "id": "property_&quot;&gt;&lt;img src=x onerror=alert(1)&gt;",
-                          "name": "&quot;&gt;&lt;img src=x onerror=alert(1)&gt;",
+                          "name": "\"&gt;&lt;img src=x onerror=alert(1)&gt;",
                           "name_href": "../././~/Foo.prototype.\"><img src=x onerror=alert(1)>.html",
                           "content": "<span>: <span>number</span></span>",
                           "anchor": {