diff --git a/docs/src/content/docs/zh-cn/guides/authoring-content.md b/docs/src/content/docs/zh-cn/guides/authoring-content.md index 8294eb10a38..3d9c32ba499 100644 --- a/docs/src/content/docs/zh-cn/guides/authoring-content.md +++ b/docs/src/content/docs/zh-cn/guides/authoring-content.md @@ -7,6 +7,22 @@ Starlight 支持在 `.md` 文件中使用完整的 [Markdown](https://daringfire 如果使用这些文件格式,请务必检查 [MDX 文档](https://mdxjs.com/docs/what-is-mdx/#markdown) 或 [Markdoc 文档](https://markdoc.dev/docs/syntax),因为 Markdown 的支持和用法可能会有所不同。 +## Frontmatter + +你可以通过设置 frontmatter 中的值来自定义 Starlight 里每个页面。 +Frontmatter 是你的文件顶部在 `---` 中间的部分。 + +```md title="src/content/docs/example.md" +--- +title: 我的页面标题 +--- + +页面内容在第二个 `---` 后面。 +``` + +每个页面都必须包含一个 `title`。 +查看 [frontmatter 参考](/zh-cn/reference/frontmatter/) 了解所有可用字段以及如何添加自定义字段。 + ## 内联样式 文本可以是**粗体**,_斜体_,或~~删除线~~。 @@ -205,6 +221,149 @@ var fun = function lang(l) { 长单行代码块不应换行。如果它们太长,它们应该水平滚动。这一行应该足够长长长长长长长长长长长长来证明这一点。 ``` +### Expressive Code 功能 + +Starlight 使用 [Expressive Code](https://github.com/expressive-code/expressive-code/tree/main/packages/astro-expressive-code) 来扩展代码块的格式化功能。 +Expressive Code 的文本标记和窗口外框插件是默认启用的。 +可以使用 Starlight 的 [`expressiveCode` 配置选项](/zh-cn/reference/configuration/#expressivecode) 来配置代码块的渲染。 + +#### 文本标记 + +你可以通过在代码块的起始行上使用 [Expressive Code 文本标记 (text markers)](https://github.com/expressive-code/expressive-code/blob/main/packages/%40expressive-code/plugin-text-markers/README.md#usage-in-markdown--mdx-documents) 在代码块里突出显示特定行或代码块的一部分。 +使用大括号 (`{ }`) 来突出显示整行,使用引号来突出显示文本字符串。 + +有三种突出显示样式:中性用于突出显示代码,绿色用于表示插入的代码,红色用于表示删除的代码。 +字符串和整行都可以使用默认的标记,也可以与 `ins=` 和 `del=` 结合使用产生所需的突出显示效果。 + +Expressive Code 提供了几种自定义你的代码示例视觉外观的选项。 +其中许多可以组合使用,以获得极具说明性的代码示例。 +请探索 [Expressive Code 文档](https://github.com/expressive-code/expressive-code/blob/main/packages/%40expressive-code/plugin-text-markers/README.md) 以了解可用的众多设置项。 +下面显示了一些最常见的示例: + +- [使用 `{ }` 标记标出整行和行范围](https://github.com/expressive-code/expressive-code/blob/main/packages/%40expressive-code/plugin-text-markers/README.md#marking-entire-lines--line-ranges): + + ```js {2-3} + function demo() { + // 这一行 (#2) 以及下一行被高亮显示 + return '这是本代码段的第 3 行'; + } + ``` + + ````md + ```js {2-3} + function demo() { + // 这一行 (#2) 以及下一行被高亮显示 + return '这是本代码段的第 3 行'; + } + ``` + ```` + +- [使用 `" "` 标记或正则表达式标出文本字符串](https://github.com/expressive-code/expressive-code/blob/main/packages/%40expressive-code/plugin-text-markers/README.md#marking-individual-text-inside-lines): + + ```js "单个词组" /甚.*表达式/ + // 单个词组也能被高亮显示 + function demo() { + return '甚至支持使用正则表达式'; + } + ``` + + ````md + ```js "单个词组" /甚.*表达式/ + // 单个词组也能被高亮显示 + function demo() { + return '甚至支持使用正则表达式'; + } + ``` + ```` + +- [使用 `ins` 或 `del` 来标记行或文本为插入或删除](https://github.com/expressive-code/expressive-code/blob/main/packages/%40expressive-code/plugin-text-markers/README.md#selecting-marker-types-mark-ins-del): + + ```js "return true;" ins="插入" del="删除" + function demo() { + console.log('这是插入以及删除类型的标记'); + // 返回语句使用默认标记类型 + return true; + } + ``` + + ````md + ```js "return true;" ins="插入" del="删除" + function demo() { + console.log('这是插入以及删除类型的标记'); + // 返回语句使用默认标记类型 + return true; + } + ``` + ```` + +- [混合语法高亮和类 `diff` 语法](https://github.com/expressive-code/expressive-code/blob/main/packages/%40expressive-code/plugin-text-markers/README.md#combining-syntax-highlighting-with-diff-like-syntax): + + ```diff lang="js" + function thisIsJavaScript() { + // 这整个代码块都会被作为 JavaScript 高亮 + // 而且我们还可以给它添加 diff 标记! + - console.log('旧的不去') + + console.log('新的不来') + } + ``` + + ````md + ```diff lang="js" + function thisIsJavaScript() { + // 这整个代码块都会被作为 JavaScript 高亮 + // 而且我们还可以给它添加 diff 标记! + - console.log('旧的不去') + + console.log('新的不来') + } + ``` + ```` + +#### 边框和标题 + +代码块可以在类似窗口的框架中呈现。 +默认情况下 shell 脚本语言(例如 `bash` 或 `sh`)会使用一个看起来像终端窗口的边框。 +其他语言在提供了标题的情况下会在一个看起来像代码编辑器的边框中显示。 + +一个代码块的可选标题可以通过在代码块的开头反引号后面添加一个 `title="..."` 属性来设置,或者通过在代码的前几行中添加一个文件名注释来设置。 + +- [通过注释添加一个文件名标签](https://github.com/expressive-code/expressive-code/blob/main/packages/%40expressive-code/plugin-frames/README.md#adding-titles-open-file-tab-or-terminal-window-title) + + ```js + // my-test-file.js + console.log('Hello World!'); + ``` + + ````md + ```js + // my-test-file.js + console.log('Hello World!'); + ``` + ```` + +- [给终端窗口添加一个标题](https://github.com/expressive-code/expressive-code/blob/main/packages/%40expressive-code/plugin-frames/README.md#adding-titles-open-file-tab-or-terminal-window-title) + + ```bash title="安装依赖…" + npm install + ``` + + ````md + ```bash title="安装依赖…" + npm install + ``` + ```` + +- [使用 `frame="none"` 禁用边框](https://github.com/expressive-code/expressive-code/blob/main/packages/%40expressive-code/plugin-frames/README.md#overriding-frame-types) + + ```bash frame="none" + echo "这个代码块即使使用了 bash 语言也不会被显示成终端窗口" + ``` + + ````md + ```bash frame="none" + echo "这个代码块即使使用了 bash 语言也不会被显示成终端窗口" + ``` + ```` + ## 其它通用 Markdown 语法 Starlight 支持所有其他 Markdown 语法,例如列表和表格。 请参阅 [Markdown 指南的 Markdown 速查表](https://www.markdownguide.org/cheat-sheet/) 以快速了解所有 Markdown 语法元素。