fix: preserve blog section headings and code comments

src/routes/blog.$.tsx

@@ -16,7 +16,7 @@ import { Breadcrumbs } from '~/components/Breadcrumbs'
 import { findMaintainerByAuthorName } from '~/utils/authors'
 import { CoverFallback } from '~/components/CoverFallback'
 import { fetchBlogPost } from '~/utils/blog.functions'
-import { parseSiteMarkdown } from '~/utils/markdown'
+import { parseBlogMarkdown } from '~/utils/blogMarkdown'
 import { getBlogPostHead, getBlogSocialImageUrl } from '~/utils/blog-post-seo'
 
 export const Route = createFileRoute('/blog/$')({
@@ -58,10 +58,7 @@ function BlogPost() {
   const videoRef = React.useRef<HTMLVideoElement>(null)
   const [startedVideo, setStartedVideo] = React.useState<string>()
   const hasStartedVideo = startedVideo === headerVideo
-  const markdown = React.useMemo(
-    () => parseSiteMarkdown(content.replace(/^# [^\n]+\n*/m, '')),
-    [content],
-  )
+  const markdown = React.useMemo(() => parseBlogMarkdown(content), [content])
   const headings = markdown.headings
 
   const isTocVisible = headings.length > 1

src/utils/blogMarkdown.ts

@@ -0,0 +1,20 @@
+import { parseSiteMarkdown } from './markdown'
+
+export function parseBlogMarkdown(content: string) {
+  const markdown = parseSiteMarkdown(content)
+  const titleIndex = markdown.children.findIndex(
+    (block) =>
+      block.type !== 'html' ||
+      !/^\s*(?:<!--[\s\S]*?-->\s*)+$/.test(block.value),
+  )
+  const title = markdown.children[titleIndex]
+
+  if (title?.type === 'heading' && title.depth === 1) {
+    markdown.children.splice(titleIndex, 1)
+    markdown.headings = markdown.headings.filter(
+      (heading) => heading.id !== title.id,
+    )
+  }
+
+  return markdown
+}

tests/blog-markdown.test.ts

@@ -0,0 +1,44 @@
+import assert from 'node:assert/strict'
+import test from 'node:test'
+import { parseBlogMarkdown } from '../src/utils/blogMarkdown'
+import { parseSiteMarkdown } from '../src/utils/markdown'
+
+test('blog title removal preserves code comments and later headings', () => {
+  for (const content of [
+    '```bash\n# Install dependencies\npnpm install\n```',
+    'Introduction\n\n# How to install\n\nInstructions',
+  ]) {
+    assert.deepEqual(parseBlogMarkdown(content), parseSiteMarkdown(content))
+  }
+})
+
+test('removes a leading title and its TOC entry, including after a comment', () => {
+  for (const prefix of ['', '<!-- Editorial note -->\n\n']) {
+    const markdown = parseBlogMarkdown(
+      prefix + '# Article\n\n## Details\n\nText',
+    )
+    assert.deepEqual(
+      markdown.headings.map((heading) => heading.level),
+      [2],
+    )
+    assert.equal(
+      markdown.children.some(
+        (block) => block.type === 'heading' && block.depth === 1,
+      ),
+      false,
+    )
+  }
+})
+
+test('preserves a later heading with the same text and its existing anchor', () => {
+  const markdown = parseBlogMarkdown('# Title\n\n# Title\n\nText')
+  assert.deepEqual(
+    markdown.headings.map((heading) => heading.id),
+    ['title-2'],
+  )
+})
+
+test('does not skip visible HTML when looking for the article title', () => {
+  const content = '<div>Introduction</div>\n\n# Keep this heading'
+  assert.deepEqual(parseBlogMarkdown(content), parseSiteMarkdown(content))
+})