feat: add frontmatter and preview helpers to Markdown class

Author: thetutlage

src/markdown.ts

@@ -8,8 +8,10 @@
  */
 
 import { VFile } from 'vfile'
+import { type Root } from 'hast'
 import { type Edge } from 'edge.js'
 import { readFile } from 'node:fs/promises'
+import { parseFrontMatter } from 'remark-mdc'
 
 import { type Cache } from './cache.ts'
 import { MarkdownParser } from './parser.ts'
@@ -216,4 +218,65 @@ export class Markdown {
 
     return result
   }
+
+  /**
+   * Extract YAML frontmatter from a markdown file or content string
+   * without running the full parsing pipeline.
+   *
+   * @param options - Options specifying either file path or content string
+   * @returns Promise resolving to the parsed frontmatter object
+   *
+   * @example
+   * ```typescript
+   * const data = await markdown.frontmatter({ file: './content.md' })
+   * console.log(data.title) // frontmatter field
+   * ```
+   */
+  async frontmatter(options: { file: string } | { content: string }) {
+    let contents: string
+    if ('file' in options) {
+      contents = await readFile(options.file, 'utf-8')
+    } else {
+      contents = options.content
+    }
+    const { data } = parseFrontMatter(contents)
+    return data
+  }
+
+  /**
+   * Parse and render only the content before the first h2 heading.
+   * Returns the same shape as `render()` but with truncated content
+   * and no table of contents.
+   *
+   * @param options - Options specifying either file path or content string to render
+   * @returns Promise resolving to rendered preview HTML with frontmatter and messages
+   *
+   * @example
+   * ```typescript
+   * const result = await markdown.preview({ file: './content.md' })
+   * console.log(result.content) // HTML before first h2
+   * ```
+   */
+  async preview(options: MarkdownOptions) {
+    const { vFile, frontmatter } = await this.parse({ ...options, toc: false })
+    const root = vFile.result as Root
+
+    const firstH2Index = root.children.findIndex(
+      (node) => node.type === 'element' && node.tagName === 'h2'
+    )
+    if (firstH2Index !== -1) {
+      root.children = root.children.slice(0, firstH2Index)
+    }
+
+    const content = await this.#edgeRenderer.render('markdown_root', {
+      node: root,
+      $renderingContext: createRenderingContext(
+        this.#mergeRendererOptions(options),
+        vFile,
+        frontmatter
+      ),
+    })
+
+    return { content, frontmatter, messages: vFile.messages }
+  }
 }

tests/markdown.spec.ts

@@ -289,4 +289,85 @@ Here is a paragraph with a [link](./foo)\`
 
     assert.snapshot(result.content).match()
   })
+
+  test('extract frontmatter from a file', async ({ assert }) => {
+    const edge = new Edge()
+    edge.mount(join(import.meta.dirname, 'fixtures/views'))
+    edge.use(edgeMarkdown, {})
+
+    const renderer = edge.share({})
+    const data = await renderer
+      .getState()
+      .$markdown.frontmatter({ file: join(import.meta.dirname, 'fixtures/front_matter.mdc') })
+
+    assert.deepEqual(data, {
+      title: 'Hello world',
+      items: ['AdonisJS', 'Lucid', 'VineJS'],
+    })
+  })
+
+  test('extract frontmatter from raw content', async ({ assert }) => {
+    const edge = new Edge()
+    edge.mount(join(import.meta.dirname, 'fixtures/views'))
+    edge.use(edgeMarkdown, {})
+
+    const renderer = edge.share({})
+    const data = await renderer.getState().$markdown.frontmatter({
+      content: dedent`
+        ---
+        title: Test doc
+        draft: true
+        ---
+
+        # Hello
+      `,
+    })
+
+    assert.deepEqual(data, { title: 'Test doc', draft: true })
+  })
+
+  test('render preview with content before first h2', async ({ assert }) => {
+    const edge = new Edge()
+    edge.mount(join(import.meta.dirname, 'fixtures/views'))
+    edge.use(edgeMarkdown, {})
+
+    const renderer = edge.share({})
+    const result = await renderer.getState().$markdown.preview({
+      content: dedent`
+        # Main title
+
+        Intro paragraph
+
+        ## First section
+
+        Section content
+      `,
+    })
+
+    assert.include(result.content, '<h1')
+    assert.include(result.content, 'Intro paragraph')
+    assert.notInclude(result.content, 'First section')
+    assert.notInclude(result.content, 'Section content')
+  })
+
+  test('preview returns full content when there is no h2', async ({ assert }) => {
+    const edge = new Edge()
+    edge.mount(join(import.meta.dirname, 'fixtures/views'))
+    edge.use(edgeMarkdown, {})
+
+    const renderer = edge.share({})
+    const result = await renderer.getState().$markdown.preview({
+      content: dedent`
+        # Main title
+
+        Some content here
+
+        More content
+      `,
+    })
+
+    assert.include(result.content, 'Main title')
+    assert.include(result.content, 'Some content here')
+    assert.include(result.content, 'More content')
+  })
 })