feat: excerpt & metadata schema

Author: zce

example/content/posts/1970-01-01-style-guide/index.md

@@ -13,6 +13,8 @@ Below is just about everything you’ll need to style in the theme. Check the so
 
 # Heading 1
 
+<!-- more -->
+
 Doloremque dolor voluptas est sequi omnis. Pariatur ut aut. Sed enim tempora qui veniam qui cum vel. Voluptas odit at vitae minima. In assumenda ut. Voluptatem totam impedit accusantium reiciendis excepturi aut qui accusamus praesentium.
 
 ## Heading 2

example/velite.config.ts

@@ -1,6 +1,6 @@
 import { defineConfig, s } from 'velite'
 
-const slugify = input =>
+const slugify = (input: string) =>
   input
     .toLowerCase()
     .replace(/\s+/g, '-')
@@ -9,6 +9,14 @@ const slugify = input =>
 const icon = s.enum(['github', 'instagram', 'medium', 'twitter', 'youtube'])
 const count = s.object({ total: s.number(), posts: s.number() }).default({ total: 0, posts: 0 })
 
+const meta = s
+  .object({
+    title: s.string().optional(),
+    description: s.string().optional(),
+    keywords: s.array(s.string()).optional()
+  })
+  .default({})
+
 export default defineConfig({
   root: 'content',
   output: {
@@ -24,9 +32,9 @@ export default defineConfig({
       pattern: 'options/index.yml',
       single: true,
       fields: s.object({
-        name: s.name(),
-        title: s.title(),
-        description: s.paragraph().optional(),
+        name: s.string().max(20),
+        title: s.string().max(99),
+        description: s.string().max(999).optional(),
         keywords: s.array(s.string()),
         author: s.object({ name: s.string(), email: s.string().email(), url: s.string().url() }),
         links: s.array(s.object({ text: s.string(), link: s.string(), type: s.enum(['navigation', 'footer', 'copyright']) })),
@@ -38,10 +46,10 @@ export default defineConfig({
       pattern: 'categories/*.yml',
       fields: s
         .object({
-          name: s.name(),
+          name: s.string().max(20),
           slug: s.slug('global'),
           cover: s.image().optional(),
-          description: s.paragraph().optional(),
+          description: s.string().max(999).optional(),
           count
         })
         .transform(data => ({ ...data, permalink: `/${data.slug}` }))
@@ -51,44 +59,47 @@ export default defineConfig({
       pattern: 'tags/index.yml',
       fields: s
         .object({
-          name: s.name(),
+          name: s.string().max(20),
           slug: s.slug('global'),
           cover: s.image().optional(),
-          description: s.paragraph().optional(),
+          description: s.string().max(999).optional(),
           count
         })
         .transform(data => ({ ...data, permalink: `/${data.slug}` }))
     },
-    // pages: {
-    //   name: 'Page',
-    //   pattern: 'pages/**/*.mdx',
-    //   fields: s
-    //     .object({
-    //       title: s.title(),
-    //       slug: s.slug('post'),
-    //       body: s.mdx()
-    //     })
-    //     .transform(data => ({ ...data, permalink: `/${data.slug}/${data.slug}` }))
-    // },
+    pages: {
+      name: 'Page',
+      pattern: 'pages/**/*.mdx',
+      fields: s
+        .object({
+          title: s.string().max(99),
+          slug: s.slug('global'),
+          body: s.markdown()
+        })
+        .transform(data => ({ ...data, permalink: `/${data.slug}` }))
+    },
     posts: {
       name: 'Post',
       pattern: 'posts/**/*.md',
       fields: s
         .object({
-          title: s.title(),
+          title: s.string().max(99),
           slug: s.slug('post'),
           date: s.isodate(),
           updated: s.isodate().optional(),
           cover: s.image().optional(),
-          description: s.paragraph().optional(),
+          description: s.string().max(999).optional(),
           draft: s.boolean().default(false),
           featured: s.boolean().default(false),
           categories: s.array(s.string()).default(['Journal']),
           tags: s.array(s.string()).default([]),
-          meta: s.meta(),
-          body: s.markdown()
+          meta: meta,
+          metadata: s.metadata({ age: 20 }),
+          summary: s.excerpt({ length: 100 }),
+          excerpt: s.excerpt({ separator: 'more', format: 'html' }),
+          content: s.markdown()
         })
-        .transform(data => ({ ...data, permalink: `/${data.slug}/${data.slug}` }))
+        .transform(data => ({ ...data, permalink: `/blog/${data.slug}` }))
     }
   },
   onSuccess: ({ categories, tags, posts }) => {

package.json

@@ -47,6 +47,9 @@
     "cac": "latest",
     "esbuild": "latest",
     "fast-glob": "latest",
+    "hast-util-excerpt": "latest",
+    "hast-util-reading-time": "latest",
+    "hast-util-truncate": "latest",
     "micromatch": "latest",
     "rehype-raw": "latest",
     "rehype-stringify": "latest",

readme.md

@@ -18,13 +18,13 @@ However, I have provided a complete [example](example) for your reference.
 - [x] markdown & yaml & json built-in support
 - [x] remark plugins & rehype plugins
 - [x] watch
-- [ ] excerpt & plain
+- [x] excerpt ~~& plain~~
+- [x] metadata field (reading-time, ~~word-count, etc.~~)
+- [ ] types generate
 - [ ] example with nextjs
-- [ ] metadata field (reading-time, word-count, etc.)
 - [ ] mdx
 - [ ] reference parent
 - [ ] nextjs plugin
-- [ ] types generate
 - [ ] image command (compress, resize, etc.)
 - [ ] docs
 

src/loaders/markdown.ts

@@ -10,18 +10,21 @@ export default defineLoader({
   name: 'markdown',
   test: /\.(md|mdx)$/,
   load: async vfile => {
-    const content = vfile.toString()
+    const raw = vfile.toString()
     // https://github.com/vfile/vfile-matter/blob/main/lib/index.js
-    const match = content.match(/^---(?:\r?\n|\r)(?:([\s\S]*?)(?:\r?\n|\r))?---(?:\r?\n|\r|$)/)
-    if (match == null) {
-      return { body: content }
-    }
-
-    // TODO: output file meta data for later use
-
-    const data = yaml.parse(match[1])
-    const raw = content.slice(match[0].length).trim()
-    // keep original content with multiple keys in vfile.data for later use
-    return Object.assign(data, { raw, excerpt: raw, plain: raw, html: raw, body: raw, code: raw })
+    const match = raw.match(/^---(?:\r?\n|\r)(?:([\s\S]*?)(?:\r?\n|\r))?---(?:\r?\n|\r|$)/)
+    const data = match == null ? {} : yaml.parse(match[1])
+    // data._file = vfile // output vfile for later use?
+    const body = match == null ? raw : raw.slice(match[0].length).trim()
+    // keep raw body with multiple keys (may be used) for later use
+    data.metadata = body // for extract metadata (reading-time, word-count, etc.)
+    data.body = body // for extract body content
+    data.content = body // for extract content
+    data.summary = body // for extract summary
+    data.excerpt = body // for extract excerpt
+    data.plain = body // for extract plain text
+    data.html = body // for markdown render
+    data.code = body // for mdx render
+    return data
   }
 })

src/plugins/rehype-extract-excerpt.ts

@@ -1,18 +1,32 @@
+import { excerpt } from 'hast-util-excerpt'
+import { truncate } from 'hast-util-truncate'
 import { visit } from 'unist-util-visit'
 
 import type { Root } from 'hast'
 import type { Plugin } from 'unified'
 
-const extractExcerpt: Plugin<[], Root> = () => (tree, file) => {
-  const lines: string[] = []
-  visit(tree, 'text', node => {
-    lines.push(node.value)
-  })
-  // extract plain
-  const plain = lines.join('').trim()
-  // extract excerpt
-  const excerpt = plain.slice(0, 100)
-  Object.assign(file.data, { plain, excerpt })
+interface ExtractExcerptOptions {
+  separator?: string
+  length?: number
 }
 
+const extractExcerpt: Plugin<[ExtractExcerptOptions], Root> =
+  ({ separator, length }) =>
+  (tree, file) => {
+    if (separator != null) {
+      tree = excerpt(tree, { comment: separator }) ?? tree
+    } else if (length != null) {
+      tree = truncate(tree, { size: length, ellipsis: '…' })
+    }
+
+    const lines: string[] = []
+    visit(tree, 'text', node => {
+      lines.push(node.value)
+    })
+
+    Object.assign(file.data, { plain: lines.join('').trim() })
+
+    return tree
+  }
+
 export default extractExcerpt

src/plugins/rehype-metadata.ts

@@ -0,0 +1,16 @@
+import { readingTime } from 'hast-util-reading-time'
+
+import type { Root } from 'hast'
+import type { Plugin } from 'unified'
+
+interface ReadingTimeOptions {
+  age: number
+}
+
+const metadata: Plugin<[ReadingTimeOptions], Root> =
+  ({ age }) =>
+  (tree, file) => {
+    Object.assign(file.data, { readingTime: Math.ceil(readingTime(tree, { age })) })
+  }
+
+export default metadata

src/shared/markdown.ts

@@ -8,18 +8,41 @@ import z from 'zod'
 
 import rehypeCopyLinkedFiles from '../plugins/rehype-copy-linked-files'
 import rehypeExtractExcerpt from '../plugins/rehype-extract-excerpt'
+import rehypeMetadata from '../plugins/rehype-metadata'
 import remarkFlattenImage from '../plugins/remark-flatten-image'
 import remarkFlattenListItem from '../plugins/remark-flatten-listitem'
 import remarkRemoveComments from '../plugins/remark-remove-comments'
 
 import type { PluggableList } from 'unified'
 
 export interface MarkdownOptions {
+  /**
+   * Enable GitHub Flavored Markdown (GFM).
+   * @default true
+   */
   gfm?: boolean
+  /**
+   * Remove html comments.
+   * @default true
+   */
   removeComments?: boolean
+  /**
+   * Flatten image paragraph.
+   * @default true
+   */
   flattenImage?: boolean
+  /**
+   * Flatten list item paragraph.
+   * @default true
+   */
   flattenListItem?: boolean
+  /**
+   * Remark plugins.
+   */
   remarkPlugins?: PluggableList
+  /**
+   * Rehype plugins.
+   */
   rehypePlugins?: PluggableList
 }
 
@@ -34,7 +57,7 @@ export const markdown = ({ gfm = true, removeComments = true, flattenImage = tru
     file.use(remarkRehype, { allowDangerousHtml: true }).use(rehypeRaw) // turn markdown syntax tree to html syntax tree, with raw html support
     if (rehypePlugins != null) file.use(rehypePlugins) // apply rehype plugins
     file.use(rehypeCopyLinkedFiles) // copy linked files to public path and replace their urls with public urls
-    file.use(rehypeExtractExcerpt) // extract excerpt and plain into file.data
+    // file.use(rehypeExtractExcerpt) // extract excerpt and plain into file.data
     // if (process.env.NODE_ENV === 'production') file.use(rehypePresetMinify) // minify html syntax tree
     file.use(rehypeStringify) // serialize html syntax tree
     try {
@@ -45,3 +68,73 @@ export const markdown = ({ gfm = true, removeComments = true, flattenImage = tru
       return value
     }
   })
+
+export interface MetadataOptions {
+  /**
+   * Age of the reader.
+   * @default 22
+   */
+  age: number
+}
+
+export interface Metadata {
+  /**
+   * Reading time in minutes.
+   */
+  readingTime: number
+}
+
+export const metadata = ({ age = 22 }: MetadataOptions) =>
+  z.string().transform(async (value, ctx) => {
+    try {
+      const file = await unified()
+        .use(remarkParse)
+        .use(remarkRehype, { allowDangerousHtml: true })
+        .use(rehypeRaw)
+        .use(rehypeMetadata, { age: age })
+        .use(rehypeStringify)
+        .process(value)
+      return file.data as unknown as Metadata
+    } catch (err: any) {
+      ctx.addIssue({ code: 'custom', message: err.message })
+      return value
+    }
+  })
+
+export interface ExcerptOptions {
+  /**
+   * Excerpt separator.
+   * @example
+   * excerpt({ separator: 'more' }) // split excerpt by `<!-- more -->`
+   */
+  separator?: string
+  /**
+   * Excerpt length.
+   * @default 200
+   */
+  length?: number
+  /**
+   * Excerpt format.
+   * @default 'plain'
+   */
+  format?: 'plain' | 'html'
+}
+
+export const excerpt = ({ separator, length = 200, format = 'plain' }: ExcerptOptions = {}) =>
+  z.string().transform(async (value, ctx) => {
+    try {
+      const file = await unified()
+        .use(remarkParse)
+        .use(remarkRehype, { allowDangerousHtml: true })
+        .use(rehypeRaw)
+        .use(rehypeExtractExcerpt, { separator, length })
+        .use(rehypeStringify)
+        .process({ value })
+
+      if (format === 'plain') return file.data.plain
+      return file.toString()
+    } catch (err: any) {
+      ctx.addIssue({ code: 'custom', message: err.message })
+      return value
+    }
+  })