test(linter): ensure rule docs are valid markdown

Author: DonIsaac

Cargo.lock

@@ -57,3 +57,4 @@ schemars            = { workspace = true, features = ["indexmap2"] }
 static_assertions = { workspace = true }
 insta             = { workspace = true }
 project-root      = { workspace = true }
+markdown          = { version = "1.0.0-alpha.18" }

crates/oxc_linter/Cargo.toml

@@ -235,12 +235,21 @@ impl RuleWithSeverity {
 #[cfg(test)]
 mod test {
     use crate::rules::RULES;
+    use markdown::{to_html_with_options, Options};
 
     #[test]
     fn ensure_documentation() {
         assert!(!RULES.is_empty());
+        let options = Options::gfm();
         for rule in RULES.iter() {
-            assert!(rule.documentation().is_some_and(|s| !s.is_empty()), "{}", rule.name());
+            assert!(
+                rule.documentation().is_some_and(|s| !s.is_empty()),
+                "Rule '{}' is missing documentation.",
+                rule.name()
+            );
+            // will panic if provided invalid html
+            let html = to_html_with_options(rule.documentation().unwrap(), &options).unwrap();
+            assert!(!html.is_empty());
         }
     }
 }

crates/oxc_linter/src/rule.rs

@@ -80,6 +80,9 @@ fn write_rule_doc_pages(table: &RuleTable, outdir: &Path) {
         let plugin_path = outdir.join(&rule.plugin);
         fs::create_dir_all(&plugin_path).unwrap();
         let page_path = plugin_path.join(format!("{}.md", rule.name));
+        if page_path.exists() {
+            fs::remove_file(&page_path).unwrap();
+        }
         println!("{}", page_path.display());
         let docs = render_rule_docs_page(rule).unwrap();
         fs::write(&page_path, docs).unwrap();