From 40a8e0ae31133fa542ae9d49feb4b12a3c80f440 Mon Sep 17 00:00:00 2001 From: 100gle Date: Mon, 28 Aug 2023 21:19:24 +0800 Subject: [PATCH 1/2] i18n(zh-cn): Update `guides/markdown-content.mdx` --- src/content/docs/zh-cn/guides/markdown-content.mdx | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/src/content/docs/zh-cn/guides/markdown-content.mdx b/src/content/docs/zh-cn/guides/markdown-content.mdx index ca1ba5f9c2db9..f44dccbc5012f 100644 --- a/src/content/docs/zh-cn/guides/markdown-content.mdx +++ b/src/content/docs/zh-cn/guides/markdown-content.mdx @@ -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`： From 99385e1d8fcb8bd5477b2bbd29492d134ade297f Mon Sep 17 00:00:00 2001 From: 100gle Date: Mon, 28 Aug 2023 21:23:45 +0800 Subject: [PATCH 2/2] chore: format content --- .../docs/zh-cn/guides/markdown-content.mdx | 54 +++++++++---------- 1 file changed, 27 insertions(+), 27 deletions(-) diff --git a/src/content/docs/zh-cn/guides/markdown-content.mdx b/src/content/docs/zh-cn/guides/markdown-content.mdx index f44dccbc5012f..ff32ae04c6303 100644 --- a/src/content/docs/zh-cn/guides/markdown-content.mdx +++ b/src/content/docs/zh-cn/guides/markdown-content.mdx @@ -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) 返回 (**在文章的列表中可见**) @@ -177,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 元素的开始，可以写 `<`。 或者，要防止 `{` 被解释为 MDX 中 JavaScript 表达式的开始，可以写 `{`。 +例如，要防止 `<` 被解释为 HTML 元素的开始，可以写 `<`。或者，要防止 `{` 被解释为 MDX 中 JavaScript 表达式的开始，可以写 `{`。 ## 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}` 作为标题： @@ -202,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" --- @@ -238,7 +238,7 @@ import ReactCounter from '../components/ReactCounter.jsx'; #### 将自定义组件分配给 HTML 元素 -使用 MDX，你可以将 Markdown 语法映射到自定义组件，而不是它们的标准 HTML 元素。 这允许你以标准的 Markdown 语法编写，但是将特殊的组件样式应用于所选的元素。 +使用 MDX，你可以将 Markdown 语法映射到自定义组件，而不是它们的标准 HTML 元素。这允许你以标准的 Markdown 语法编写，但是将特殊的组件样式应用于所选的元素。 将自定义组件导入 `.mdx`文件，然后导出将标准 HTML 元素映射到自定义组件的`components`对象： @@ -263,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) 导入多个页面。 @@ -355,10 +355,10 @@ const posts = await Astro.glob('../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` 语句导出数据。 @@ -380,7 +380,7 @@ import {Content as PromoBanner} from '../components/promoBanner.md'; 与其将 Markdown/MDX 文件放在 'src/pages/' 目录中来创建页面路由，不如[动态路由](/zh-cn/core-concepts/routing/#动态路由)。 -要访问 Markdown 内容，请将 `` 组件传递给 Astro 页面的 `props`。 然后，你可以从 `Astro.props` 中检索该组件并在页面模板中渲染它。 +要访问 Markdown 内容，请将 `` 组件传递给 Astro 页面的 `props`。然后，你可以从 `Astro.props` 中检索该组件并在页面模板中渲染它。 ```astro title="src/pages/[slug].astro" {9-11} "Content" "Astro.props.post" --- @@ -445,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 以获取特定的安装说明。 @@ -473,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 文件中的所有标题元素（`

` 到 `

`），并提供 `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`： @@ -539,7 +539,7 @@ export default { :::tip - `data.astro.frontmatter` 包含给定 Markdown 或 MDX 文档的所有属性。 这允许你修改现有的 frontmatter 属性，或者从现有的 frontmatter 计算新属性。 + `data.astro.frontmatter` 包含给定 Markdown 或 MDX 文档的所有属性。这允许你修改现有的 frontmatter 属性，或者从现有的 frontmatter 计算新属性。 ::: 2. 将此插件应用于你的 `markdown` 或 `mdx` 集成配置： @@ -576,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 插件集： @@ -603,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'; @@ -625,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 文件中的所有代码块（\`\`\`）。 - [内置的 `` 组件](/zh-cn/reference/api-reference/#code-) 中的内容（由 Shiki 提供支持）。 - [`` 组件](/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'; @@ -691,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)。 @@ -701,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" ---