Nuxt Content 项目中的 Markdown 使用指南

Nuxt Content 项目中的 Markdown 使用指南

content The file-based CMS for your Nuxt application, powered by Markdown and Vue components. 项目地址: https://gitcode.com/gh_mirrors/con/content

前言

在 Nuxt Content 项目中，Markdown 是构建内容的核心技术。本文将深入探讨如何在 Nuxt 应用中高效使用 Markdown，包括基础用法、高级特性以及最佳实践。

基础使用

1. 定义内容集合

首先需要在配置文件中定义内容集合：

// content.config.ts
import { defineCollection, defineContentConfig, z } from '@nuxt/content'

export default defineContentConfig({
  collections: {
    blog: defineCollection({
      type: 'page',
      source: 'blog/*.md',
      schema: z.object({
        date: z.string()
      })
    })
  }
})

这个配置定义了一个名为"blog"的集合，它会自动加载blog目录下的所有Markdown文件。

2. 创建Markdown文件

在content/blog/目录下创建Markdown文件：

---
date: 2023-01-01
---

# 我的第一篇博客

这是博客正文内容...

3. 查询Markdown内容

可以通过以下方式查询内容：

// 获取特定文章
const post = await queryCollection('blog').path('/blog/my-post').first()

// 获取所有文章并按日期排序
const allPosts = await queryCollection('blog').order('date', 'DESC').all()

4. 渲染Markdown内容

使用<ContentRenderer>组件渲染Markdown：

<script setup>
const slug = useRoute().params.slug
const { data: post } = await useAsyncData(`blog-${slug}`, () => {
  return queryCollection('blog').path(`/blog/${slug}`).first()
})
</script>

<template>
  <ContentRenderer :value="post" />
</template>

高级特性

1. Frontmatter 元数据

Frontmatter 是Markdown文件顶部的YAML块，用于定义页面元数据：

---
title: '页面标题'
description: '页面描述'
customField: '自定义值'
---

# 页面内容

这些元数据可以在查询结果中访问：

const page = await queryCollection('content').path('/').first()
console.log(page.title) // "页面标题"

2. MDC 语法

MDC (Markdown Components) 是Nuxt Content扩展的语法，允许在Markdown中嵌入Vue组件：

::alert{type="warning"}
这是一个警告组件
::

3. 组件使用技巧

块级组件

::card
卡片内容...
::

对应的Vue组件：

<template>
  <div class="card">
    <slot />
  </div>
</template>

具名插槽

::hero
主标题

#description
描述内容
::

对应的Vue组件：

<template>
  <section>
    <h1><slot /></h1>
    <slot name="description" />
  </section>
</template>

属性传递

::alert{type="error" icon="exclamation-circle"}
错误信息
::

4. 数据绑定

可以在Markdown中绑定动态数据：

# 你好, {{ $doc.name || '世界' }}!

最佳实践

1. 内容摘要：使用<!--more-->标记分隔摘要和正文
2. 代码高亮：利用Shiki实现专业级的代码高亮
3. 图片管理：将图片放在public目录并引用
4. 组件组织：在components/content/目录下组织内容相关组件
5. 类型安全：为集合定义严格的schema确保数据一致性

常见问题

Q: 如何在Markdown中使用自定义组件？ A: 将组件放在components/content/目录下或注册为全局组件

Q: 如何覆盖默认的Markdown渲染行为？ A: 创建对应的Prose组件进行覆盖，如ProseP、ProseH1等

Q: 如何实现多语言内容？ A: 利用Nuxt的i18n模块结合内容集合实现

总结

Nuxt Content的Markdown支持不仅保留了传统Markdown的简洁性，还通过MDC语法扩展了Vue组件的强大功能。掌握这些特性可以显著提升内容管理的灵活性和开发效率。

content The file-based CMS for your Nuxt application, powered by Markdown and Vue components. 项目地址: https://gitcode.com/gh_mirrors/con/content