Skip to content

i18n(zh-cn): Update guides/markdown-content.mdx #4402

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
100gle wants to merge 2 commits into from
Closed

i18n(zh-cn): Update guides/markdown-content.mdx #4402

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
40a8e0a
i18n(zh-cn): Update `guides/markdown-content.mdx`
100gle Aug 28, 2023
99385e1
chore: format content
100gle Aug 28, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
58 changes: 31 additions & 27 deletions src/content/docs/zh-cn/guides/markdown-content.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,14 +52,14 @@ title: Hello, World
- **粗体** and _斜体。_
- 列表
- [链接](https://astro.build)
- 等等!
- 等等！
```

📚 阅读更多关于 Astro [基于文件的路由](/zh-cn/core-concepts/routing/)或创建[动态路由](/zh-cn/core-concepts/routing/#动态路由)的选项。

### 草稿页面

`draft: true` 是一个可选的 frontmatter 值，它将标记单个 Markdown 或 MDX 页面或文章为“未发布”。 默认情况下，此页面将是：
`draft: true` 是一个可选的 frontmatter 值，它将标记单个 Markdown 或 MDX 页面或文章为“未发布”。默认情况下，此页面将是：

- 排除在网站构建之外 (**不会有页面被构建**)
- 由 [`Astro.glob()`](/zh-cn/reference/api-reference/#astroglob) 返回 (**在文章的列表中可见**)
Expand Down Expand Up @@ -91,6 +91,10 @@ const posts = await Astro.glob('../pages/post/*.md');
const nonDraftPosts = posts.filter((post) => !post.frontmatter.draft);
```

:::note[使用内容集合？]
尽管这个功能不支持内容集合，但你可以使用 [集合查询过滤器](/zh-cn/guides/content-collections/#筛选集合查询) 来过滤你的草稿文章。
:::

#### 启用构建草稿页面

要默认启用构建草稿页面，请通过添加 `drafts: true`到 `markdown` 或 `mdx` 集成来更新 `astro.config.mjs`：
Expand Down Expand Up @@ -173,21 +177,21 @@ title: My page of content

### 转义特殊字符

某些字符在 Markdown 和 MDX 中具有特殊含义。 如果你想显示它们，你可能需要使用不同的语法。 要做到这一点，你可以使用这些字符的 [HTML 实体](https://developer.mozilla.org/zh-CN/docs/Glossary/Entity)。
某些字符在 Markdown 和 MDX 中具有特殊含义。如果你想显示它们，你可能需要使用不同的语法。要做到这一点，你可以使用这些字符的 [HTML 实体](https://developer.mozilla.org/zh-CN/docs/Glossary/Entity)。

例如，要防止 `<` 被解释为 HTML 元素的开始，可以写 `&lt;`。 或者，要防止 `{` 被解释为 MDX 中 JavaScript 表达式的开始，可以写 `&lcub;`。
例如，要防止 `<` 被解释为 HTML 元素的开始，可以写 `&lt;`。或者，要防止 `{` 被解释为 MDX 中 JavaScript 表达式的开始，可以写 `&lcub;`。

## MDX 独有特性

添加 Astro [MDX 集成](/zh-cn/guides/integrations-guide/mdx/)可以使用 JSX 变量、表达式和组件来增强你的 Markdown 编写体验。

它还为标准 MDX 添加了额外的功能，包括对 [MDX 中的 Markdown 样式 frontmatter](https://mdxjs.com/guides/frontmatter/)的支持。 这允许你使用 Astro 的大多数内置 Markdown 功能，例如 [frontmatter `layout`](#frontmatter-layout) 属性和 [草稿页面](#草稿页面) 的设置。
它还为标准 MDX 添加了额外的功能，包括对 [MDX 中的 Markdown 样式 frontmatter](https://mdxjs.com/guides/frontmatter/)的支持。这允许你使用 Astro 的大多数内置 Markdown 功能，例如 [frontmatter `layout`](#frontmatter-layout) 属性和 [草稿页面](#草稿页面) 的设置。

`.mdx` 文件必须使用 [MDX 语法](https://mdxjs.com/docs/what-is-mdx/#mdx-syntax)编写，而不是 Astro 的 HTML 语法。

### 在 MDX 中使用导出的变量

MDX 支持使用 `export` 语句将变量添加到你的 MDX 内容中。 这些变量既可以在模板本身中访问，也可以在[导入文件](#导入-markdown)时以命名属性的形式访问。
MDX 支持使用 `export` 语句将变量添加到你的 MDX 内容中。这些变量既可以在模板本身中访问，也可以在[导入文件](#导入-markdown)时以命名属性的形式访问。

例如，你可以从 MDX 页面或组件中导出一个 `title` 字段，以便使用 `{JSX expressions}` 作为标题：

Expand All @@ -198,7 +202,7 @@ export const title = '我的第一篇 MDX 文章'
```
### 在 MDX 中使用 Frontmatter 变量

Astro MDX 集成默认支持在 MDX 中使用 frontmatter。 在 Markdown 文件中添加 frontmatter 属性，这些变量可在模板中、其 [`layout` 组件](#frontmatter-layout)中以及在 [导入文件](#导入-markdown)时以命名属性的形式访问。
Astro MDX 集成默认支持在 MDX 中使用 frontmatter。在 Markdown 文件中添加 frontmatter 属性，这些变量可在模板中、其 [`layout` 组件](#frontmatter-layout)中以及在 [导入文件](#导入-markdown)时以命名属性的形式访问。

```mdx title="/src/pages/posts/post-1.mdx"
---
Expand Down Expand Up @@ -234,7 +238,7 @@ import ReactCounter from '../components/ReactCounter.jsx';

#### 将自定义组件分配给 HTML 元素

使用 MDX，你可以将 Markdown 语法映射到自定义组件，而不是它们的标准 HTML 元素。 这允许你以标准的 Markdown 语法编写，但是将特殊的组件样式应用于所选的元素。
使用 MDX，你可以将 Markdown 语法映射到自定义组件，而不是它们的标准 HTML 元素。这允许你以标准的 Markdown 语法编写，但是将特殊的组件样式应用于所选的元素。

将自定义组件导入 `.mdx`文件，然后导出将标准 HTML 元素映射到自定义组件的`components`对象：

Expand All @@ -259,7 +263,7 @@ const props = Astro.props;

## 导入 Markdown

你可以直接将 Markdown 和 MDX 文件导入到你的 Astro 文件中。 这使你可以访问它们的 Markdown 内容，以及可以在 Astro 的类 JSX 表达式中使用的其他属性，例如 frontmatter 值。
你可以直接将 Markdown 和 MDX 文件导入到你的 Astro 文件中。这使你可以访问它们的 Markdown 内容，以及可以在 Astro 的类 JSX 表达式中使用的其他属性，例如 frontmatter 值。

你可以使用 `import` 语句导入一个特定的页面，也可以使用 [`Astro.glob()`](/zh-cn/guides/imports/#astroglob) 导入多个页面。

Expand Down Expand Up @@ -351,10 +355,10 @@ const posts = await Astro.glob<Frontmatter>('../pages/post/*.md');
- **`file`** - 绝对文件路径（例如 `/home/user/projects/.../file.md`）。
- **`url`** - 如果是页面，则为页面的 URL（例如 `/zh-cn/guides/markdown-content`）。
- **`frontmatter`** - 包含文件中指定的 YAML frontmatter 中的任何数据。
- **`getHeadings`** - 一个异步函数，返回文件中所有标题（即 `h1 -> h6` 元素）的数组。 每个标题的 `slug` 对应于给定标题的生成的 ID，可用于锚链接。 此列表遵循类型：`{ depth: number; slug: string; text: string }[]`。
- **`getHeadings`** - 一个异步函数，返回文件中所有标题（即 `h1 -> h6` 元素）的数组。每个标题的 `slug` 对应于给定标题的生成的 ID，可用于锚链接。此列表遵循类型：`{ depth: number; slug: string; text: string }[]`。
- **`Content`** - 一个组件，返回文件的完整渲染内容。
- **（仅 Markdown)`rawContent()`** - 一个函数，返回原始 Markdown 文档作为字符串。
- **（仅 Markdown）`compiledContent()`** - 一个函数，返回将 Markdown 文档编译为 HTML 字符串。 请注意，这不包括 frontmatter 中配置的布局！ 只会将 Markdown 文档本身作为 HTML 返回。
- **（仅 Markdown）`compiledContent()`** - 一个函数，返回将 Markdown 文档编译为 HTML 字符串。请注意，这不包括 frontmatter 中配置的布局！只会将 Markdown 文档本身作为 HTML 返回。
- **（仅 MDX）** - MDX 文件还可以使用 `export` 语句导出数据。


Expand All @@ -376,7 +380,7 @@ import {Content as PromoBanner} from '../components/promoBanner.md';

与其将 Markdown/MDX 文件放在 'src/pages/' 目录中来创建页面路由，不如[动态路由](/zh-cn/core-concepts/routing/#动态路由)。

要访问 Markdown 内容，请将 `<Content/>` 组件传递给 Astro 页面的 `props`。 然后，你可以从 `Astro.props` 中检索该组件并在页面模板中渲染它。
要访问 Markdown 内容，请将 `<Content/>` 组件传递给 Astro 页面的 `props`。然后，你可以从 `Astro.props` 中检索该组件并在页面模板中渲染它。

```astro title="src/pages/[slug].astro" {9-11} "Content" "Astro.props.post"
---
Expand Down Expand Up @@ -441,15 +445,15 @@ import Heading from '../Heading.astro';

## 配置 Markdown

Astro 中的 Markdown 支持由 [remark](https://remark.js.org/) 提供，remark 是一个强大的解析和处理工具，拥有一个活跃的生态系统。 目前不支持其他 Markdown 解析器，如 Pandoc 和 markdown-it。
Astro 中的 Markdown 支持由 [remark](https://remark.js.org/) 提供，remark 是一个强大的解析和处理工具，拥有一个活跃的生态系统。目前不支持其他 Markdown 解析器，如 Pandoc 和 markdown-it。

Astro 默认应用 [GitHub 风格的 Markdown](https://github.com/remarkjs/remark-gfm) 和 [SmartyPants](https://github.com/silvenon/remark-smartypants) 插件。 这带来了一些便利，例如从文本生成可点击的链接，并格式化 [引用和 em-dashes](https://daringfireball.net/projects/smartypants/)。
Astro 默认应用 [GitHub 风格的 Markdown](https://github.com/remarkjs/remark-gfm) 和 [SmartyPants](https://github.com/silvenon/remark-smartypants) 插件。这带来了一些便利，例如从文本生成可点击的链接，并格式化 [引用和 em-dashes](https://daringfireball.net/projects/smartypants/)。

你可以在 `astro.config.mjs` 中自定义 remark 解析 Markdown 的方式。 请参阅完整的 [Markdown 配置选项](/zh-cn/reference/configuration-reference/#markdown-选项)列表，。
你可以在 `astro.config.mjs` 中自定义 remark 解析 Markdown 的方式。请参阅完整的 [Markdown 配置选项](/zh-cn/reference/configuration-reference/#markdown-选项)列表，。

### Markdown 插件

Astro 支持添加第三方 [remark](https://github.com/remarkjs/remark) 和 [rehype](https://github.com/rehypejs/rehype) 插件来解析 Markdown 和 MDX。 这些插件允许你扩展你的 Markdown，以获得新的功能，例如 [自动生成目录](https://github.com/remarkjs/remark-toc)，[应用可访问的表情符号标签](https://github.com/florianeckerstorfer/remark-a11y-emoji)，以及 [为你的 Markdown 添加样式](/zh-cn/guides/styling/#markdown-样式)。
Astro 支持添加第三方 [remark](https://github.com/remarkjs/remark) 和 [rehype](https://github.com/rehypejs/rehype) 插件来解析 Markdown 和 MDX。这些插件允许你扩展你的 Markdown，以获得新的功能，例如 [自动生成目录](https://github.com/remarkjs/remark-toc)，[应用可访问的表情符号标签](https://github.com/florianeckerstorfer/remark-a11y-emoji)，以及 [为你的 Markdown 添加样式](/zh-cn/guides/styling/#markdown-样式)。

我们鼓励你浏览 [awesome-remark](https://github.com/remarkjs/awesome-remark) 和 [awesome-rehype](https://github.com/rehypejs/awesome-rehype) 来查看流行的插件！请参阅每个插件自己的 README 以获取特定的安装说明。

Expand All @@ -469,13 +473,13 @@ export default defineConfig({
});
```

请注意，默认情况下，`remarkToc`需要页面上的 “ToC” 或 “Table of Contents” [标题](https://github.com/remarkjs/remark-toc#optionsheading)（不区分大小写）才能显示目录。
请注意，默认情况下，`remarkToc`需要页面上的“ToC”或“Table of Contents” [标题](https://github.com/remarkjs/remark-toc#optionsheading)（不区分大小写）才能显示目录。

#### 标题 ID 和插件

Astro 将 `id` 属性注入到 Markdown 和 MDX 文件中的所有标题元素（`<h1>` 到 `<h6>`），并提供 `getHeadings()` 实用程序，用于在 [Markdown 导出的属性](#导出的属性) 中检索这些 ID。

你可以通过添加注入 `id` 属性的 rehype 插件（例如 `rehype-slug`）来自定义这些标题ID。你的自定义 ID（而不是 Astro 的默认值）将反映在 HTML 输出和 `getHeadings()` 返回的项目中。
你可以通过添加注入 `id` 属性的 rehype 插件（例如 `rehype-slug`）来自定义这些标题 ID。你的自定义 ID（而不是 Astro 的默认值）将反映在 HTML 输出和 `getHeadings()` 返回的项目中。

默认情况下，Astro 会在你的 rehype 插件运行后注入 `id` 属性。如果你的自定义 rehype 插件之一需要访问 Astro 注入的 ID，你可以直接导入和使用 Astro 的 `rehypeHeadingIds` 插件。确保在任何依赖它的插件之前添加 `rehypeHeadingIds`：

Expand Down Expand Up @@ -535,7 +539,7 @@ export default {
:::tip
<Since v="2.0.0" />

`data.astro.frontmatter` 包含给定 Markdown 或 MDX 文档的所有属性。 这允许你修改现有的 frontmatter 属性，或者从现有的 frontmatter 计算新属性。
`data.astro.frontmatter` 包含给定 Markdown 或 MDX 文档的所有属性。这允许你修改现有的 frontmatter 属性，或者从现有的 frontmatter 计算新属性。
:::

2. 将此插件应用于你的 `markdown` 或 `mdx` 集成配置：
Expand Down Expand Up @@ -572,7 +576,7 @@ export default {

### 从 MDX 扩展 Markdown 配置

Astro 的 MDX 集成默认情况下会扩展 [你的项目的现有 Markdown 配置](/zh-cn/reference/configuration-reference/#markdown-选项)。 要覆盖单个选项，你可以在 MDX 配置中指定它们的等效项。
Astro 的 MDX 集成默认情况下会扩展 [你的项目的现有 Markdown 配置](/zh-cn/reference/configuration-reference/#markdown-选项)。要覆盖单个选项，你可以在 MDX 配置中指定它们的等效项。

下面的示例禁用了 GitHub-Flavored Markdown，并为 MDX 文件应用了不同的 remark 插件集：

Expand All @@ -599,7 +603,7 @@ export default defineConfig({
});
```

要避免从 MDX 扩展你的 Markdown 配置，请将 [`extendMarkdownConfig` 选项](/zh-cn/guides/integrations-guide/mdx/#extendmarkdownconfig) (默认开启)设置为 `false`:
要避免从 MDX 扩展你的 Markdown 配置，请将 [`extendMarkdownConfig` 选项](/zh-cn/guides/integrations-guide/mdx/#extendmarkdownconfig) (默认开启) 设置为 `false`:

```ts title="astro.config.mjs"
import { defineConfig } from 'astro/config';
Expand All @@ -621,17 +625,17 @@ export default defineConfig({

### 语法高亮

Astro 内置支持 [Shiki](https://shiki.matsu.io/) 和 [Prism](https://prismjs.com/)。 这为：
Astro 内置支持 [Shiki](https://shiki.matsu.io/) 和 [Prism](https://prismjs.com/)。这为：

- Markdown 或 MDX 文件中的所有代码块（\`\`\`）。
- [内置的 `<Code />` 组件](/zh-cn/reference/api-reference/#code-) 中的内容（由 Shiki 提供支持）。
- [`<Prism />` 组件](/zh-cn/reference/api-reference/#prism-) 中的内容（由 Prism 提供支持）。

Shiki 默认启用，预配置为 `github-dark` 主题。 编译输出将限于内联 `style`，而不会包含任何冗余的 CSS 类、样式表或客户端 JS。
Shiki 默认启用，预配置为 `github-dark` 主题。编译输出将限于内联 `style`，而不会包含任何冗余的 CSS 类、样式表或客户端 JS。

#### Shiki 配置

Shiki 是我们的默认语法高亮器。 你可以通过 `shikiConfig` 对象配置所有选项，如下所示：
Shiki 是我们的默认语法高亮器。你可以通过 `shikiConfig` 对象配置所有选项，如下所示：

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
Expand Down Expand Up @@ -687,7 +691,7 @@ export default defineConfig({

#### Prism 配置

如果你选择使用 Prism，Astro 将应用 Prism 的 CSS 类。 请注意，**你需要自己的 CSS 样式表**，以使语法高亮显示出来！
如果你选择使用 Prism，Astro 将应用 Prism 的 CSS 类。请注意，**你需要自己的 CSS 样式表**，以使语法高亮显示出来！

1. 从可用的 [Prism 主题](https://github.com/PrismJS/prism-themes) 中选择一个预制的样式表。
2. 将此样式表添加到 [你的项目的 `public/` 目录](/zh-cn/core-concepts/project-structure/#public)。
Expand All @@ -697,9 +701,9 @@ export default defineConfig({

## 请求远程 Markdown

Astro 主要设计用于可以保存在项目目录中的本地 Markdown 文件。 但是，在某些情况下，你可能需要从远程源获取 Markdown。 例如，你可能需要在构建网站时（或在使用 [SSR](/zh-cn/guides/server-side-rendering/) 时，用户向网站发出请求时）从远程 API 获取并呈现 Markdown。
Astro 主要设计用于可以保存在项目目录中的本地 Markdown 文件。但是，在某些情况下，你可能需要从远程源获取 Markdown。例如，你可能需要在构建网站时（或在使用 [SSR](/zh-cn/guides/server-side-rendering/) 时，用户向网站发出请求时）从远程 API 获取并呈现 Markdown。

**Astro 不包含对远程 Markdown 的内置支持！** 要获取远程 Markdown 并将其呈现为 HTML，你需要从 npm 安装并配置自己的 Markdown 解析器。 这将**不会**从你配置的 Astro 的内置 Markdown 和 MDX 设置中继承。 在将其添加到你的项目之前，请确保你了解这些限制。
**Astro 不包含对远程 Markdown 的内置支持！** 要获取远程 Markdown 并将其呈现为 HTML，你需要从 npm 安装并配置自己的 Markdown 解析器。这将**不会**从你配置的 Astro 的内置 Markdown 和 MDX 设置中继承。在将其添加到你的项目之前，请确保你了解这些限制。

```astro title="src/pages/remote-example.astro"
---
Expand Down