Markdown

简介

我们创建了 MDC 语法来增强 Markdown，并使您能够利用带插槽和道具的 Vue 组件的强大功能。

前置内容

前置内容是基于 Markdown 的 CMS 的一个约定，用于为页面提供元数据，例如描述或标题。在 Nuxt 内容中，前置内容使用 YAML 语法，带有 key: value 对。

这些数据在渲染内容时可用，并且可以保存您需要的任何信息。

语法

您可以在 content/ 目录中 Markdown 文件的顶部声明一个前置内容块，使用 --- 标识符。

---
title: 'Title of the page'
description: 'meta description of the page'
---

<!-- Content of the page -->

原生参数

当与 <ContentDoc> 或 文档驱动模式 一起使用来显示当前页面时， useContentHead() 可组合函数 将用于设置页面的元数据。

摘录

可以使用 <!--more--> 作为分隔符从内容中提取内容摘录或摘要。

---
title: Introduction
---

Learn how to use @nuxt/content.
<!--more-->
Full amount of content beyond the more divider.

除非在“前置内容”道具中定义，否则 description 属性将包含摘录内容。

如果文本中没有 <!--more--> 分隔符，则摘录未定义。

示例变量将注入到文档中

{
  "_id": "content:index.md"
  "excerpt": Object
  "body": Object
  // ... other keys
}

代码高亮

Nuxt 内容使用 Shiki，它使用 VSCode 主题对令牌进行着色。

代码高亮在 ProsePre 和 ProseCodeInline 上都有效。

代码块的每一行都在 line 属性中获得其行号，因此可以标记或单独设置行样式。

图片

您可以在 public 目录中添加图片

content/
  index.md
public/
  img/
    image.png
nuxt.config.ts
package.json
tsconfig.json

然后在 content 目录中的 Markdown 文件中使用它们，如下所示

![my image](/img/image.png)

Vue 组件

在 components/content/ 目录中创建的每个 Vue 组件都将在 Markdown 文件中可用。

块组件

块组件是接受 Markdown 内容或另一个组件作为插槽的组件。

该组件必须包含以下任一项：

• 一个 <slot /> 来接受原始文本或另一个组件。
• The <ContentSlot /> component to accept formatted text.

在 Markdown 文件中，使用带 :: 标识符的组件。

::card
The content of the card
::

插槽

组件的插槽可以接受内容或其他组件。

• default 插槽渲染块组件内部的顶层内容。
• 命名 插槽使用 # 标识符来渲染相应的内容。

::hero
Default slot text

#description
This will be rendered inside the `description` slot.
::

嵌套

MDC 支持通过缩进在插槽中嵌套组件。

::hero
  :::card
    A nested card
    ::card
      A super nested card
    ::
  :::
::

Markdown 渲染

The <ContentSlot /> component is auto-imported by Nuxt Content. It acts as a special slot that accepts rich text rendered by Markdown.

The unwrap prop accepts an HTML tag that will be used to unwrap the content, useful when using tags such as title tags (<h1>, <h2>, ...) or inline tags (<button>, <a>, ...).

<!-- components/content/TheTitle.vue -->
<template>
  <h1 class="text-4xl">
    <ContentSlot :use="$slots.default" unwrap="p" />
  </h1>
</template>

The <ContentSlot /> component can act as a named slot with the use property

<ContentSlot :use="$slots.description" unwrap="p">

内联组件

内联组件是没有插槽或 <ContentSlot /> 的组件。

它们可以使用 : 标识符。

# Title

:banner

如果您想在内联组件后面使用特定的字符，例如 -、_ 或 :，您可以在其后使用一个虚拟道具指定符。

:hello{}-world

在此示例中，:hello{} 将搜索 <Hello /> 组件，而 -world 将是纯文本。

道具

有两种方法可以使用 MDC 将道具传递给组件。

内联方法

The {} identifier passes props to components in a terse way by using a key=value syntax.

::alert{type="warning"}
The **alert** component.
::

多个道具可以用空格隔开

::alert{type="warning" icon="exclamation-circle"}
Oops! An error occurred
::

The v-bind shorthand : can be also be used to bind a prop to a value in the front matter.

---
type: "warning"
---

::alert{:type="type"}
Your warning
::

如果您想将数组或对象作为道具传递给组件，您可以将它们作为 JSON 字符串传递，并将道具键前缀为冒号以自动解码 JSON 字符串。请注意，在这种情况下，您应该对值字符串使用单引号，这样您就可以使用双引号传递有效的 JSON 字符串

::dropdown{:items='["Nuxt", "Vue", "React"]'}
::

YAML 方法

YAML 方法使用 --- 标识符来声明每行一个道具，这对于可读性很有用。

::icon-card
---
icon: IconNuxt
description: Harness the full power of Nuxt and the Nuxt ecosystem.
title: Nuxt Architecture.
---
::

跨度文本

要在文本中创建内联跨度，可以使用 [] 标识符。

Hello [World]{style="background-color: var(--color-primary-500)"}!

属性

属性对于突出显示和修改段落的一部分很有用。语法与内联组件和 Markdown 链接语法几乎相同。

可能的值是所有命名属性，使用 .class-name 表示法的类，以及使用 #id-name 表示的 ID。

Hello [World]{style="color: green;" .custom-class #custom-id}!

除了 mdc 组件和 span 外，属性语法还可以用于图像、链接、内联 code、粗体 和 斜体 文本。

Attributes work on:

- ![](/favicon.ico){style="display: inline; margin: 0;"} image,
- [link](#attributes){style="background-color: pink;"}, `code`{style="color: cyan;"},
- _italic_{style="background-color: yellow; color:black;"} and **bold**{style="background-color: lightgreen;"} texts.

在 Markdown 中绑定数据

您可以使用 {{ $doc.variable || 'defaultValue' }} 语法在 Markdown 文档中绑定数据。这些值可以在文档顶部的 YAML 前端 matter 中定义，在每个 MDC 组件中定义，或者使用 <ContentRendererMarkdown> 组件的 data 属性注入。

示例 1：在 YAML 中定义

---
title: 'Title of the page'
description: 'meta description of the page'
customVariable: 'Custom Value'
---

# The Title is {{ $doc.title }} and customVariable is {{ $doc.customVariable || 'defaultValue' }}

示例 2：使用 <ContentRendererMarkdown> 在外部定义

<template>
  <div>
    <ContentRendererMarkdown :value="data" :data="mdcVars"/>
    <button type="button" v-on:click="mdcVars.name = 'Hugo'">Change name</button>
  </div>
</template>

<script setup lang="ts">
const { data } = await useAsyncData(() => queryContent('test').findOne());
const mdcVars = ref({ name: 'Maxime'});
</script>

# Hello {{ $doc.name || 'World' }}

散文组件

在 Nuxt Content 中，散文表示由 Markdown 语法生成的 HTML 标签，例如标题级别和链接。

对于每个 HTML 标签，都会使用一个 Vue 组件，允许您在需要时覆盖它们，例如 <p> 会变成 <ProseP>。

如果您想自定义散文组件，以下是一些建议的步骤

• 查看原始 组件源代码。
• 使用完全相同的属性。
• 在您的 components/content/ 目录中，使用相同的名称。
• 让它成为您的 🚀。