diff --git a/Cargo.lock b/Cargo.lock
index 40f0bc8d5fbd7..05276a72a95df 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -937,7 +937,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e310b3a6b5907f99202fcdb4960ff45b93735d7c7d96b760fcff8db2dc0e103d"
 dependencies = [
  "cfg-if",
- "windows-targets 0.48.5",
+ "windows-targets 0.52.6",
 ]
 
 [[package]]
@@ -997,6 +997,15 @@ dependencies = [
  "url",
 ]
 
+[[package]]
+name = "markdown"
+version = "1.0.0-alpha.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4e61c5c85b392273c4d4ea546e6399ace3e3db172ab01b6de8f3d398d1dbd2ec"
+dependencies = [
+ "unicode-id",
+]
+
 [[package]]
 name = "memchr"
 version = "2.7.4"
@@ -1524,6 +1533,7 @@ dependencies = [
  "json-strip-comments",
  "language-tags",
  "lazy_static",
+ "markdown",
  "memchr",
  "mime_guess",
  "once_cell",
@@ -2873,6 +2883,12 @@ version = "0.3.15"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "08f95100a766bf4f8f28f90d77e0a5461bbdb219042e7679bebe79004fed8d75"
 
+[[package]]
+name = "unicode-id"
+version = "0.3.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b1b6def86329695390197b82c1e244a54a131ceb66c996f2088a3876e2ae083f"
+
 [[package]]
 name = "unicode-id-start"
 version = "1.2.0"
diff --git a/crates/oxc_linter/Cargo.toml b/crates/oxc_linter/Cargo.toml
index 3ce4efdf536bc..3df3bd116666e 100644
--- a/crates/oxc_linter/Cargo.toml
+++ b/crates/oxc_linter/Cargo.toml
@@ -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" }
diff --git a/crates/oxc_linter/src/rule.rs b/crates/oxc_linter/src/rule.rs
index 3fb081fb1315d..d9a6a499eece1 100644
--- a/crates/oxc_linter/src/rule.rs
+++ b/crates/oxc_linter/src/rule.rs
@@ -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());
         }
     }
 }
diff --git a/tasks/website/src/linter/rules/mod.rs b/tasks/website/src/linter/rules/mod.rs
index 3823afa10cdcf..e03b2dbf977eb 100644
--- a/tasks/website/src/linter/rules/mod.rs
+++ b/tasks/website/src/linter/rules/mod.rs
@@ -91,6 +91,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();