Logo
文章 项目 相册

通过标注框、Expressive Code 代码块、图片说明指令、视频嵌入、样式链接、徽章和详情折叠，增强 Markdown 的表现力。

Markdown 增强语法
8 mins
1666 words
Loading views
推荐 Litos文档

本指南在 markdown-mdx-extended-features 的基础上做了少量修改。

标注框（Callouts）h2

由 rehype-callouts 插件支持，可在 plugins/index.ts 中配置该插件。

若修改了 theme 配置（默认值为 'vitepress'），还需同步更新 src/styles/pro.css 中引入的 CSS 文件（@import 'rehype-callouts/theme/你的配置'）。

<!-- 标注框类型名称不区分大小写：'Note'、'NOTE' 和 'note' 等价。 -->


<!-- vitepress -->


<!-- 这是一个不可折叠的标注框 -->


> [!note]
> 注意内容。


> [!tip]
> 提示内容。


> [!important]
> 重要内容。


> [!warning]
> 警告内容。


> [!caution]
> 注意内容。


> [!caution]- 这是一个**可折叠**的标注框
> 注意内容。


> [!note]+ 这是一个**可折叠**的标注框
> 注意内容。
> ` ` `


> [!note]
> 注意 `内容`。


> [!tip]
> 提示 `内容`。


> [!important]
> 重要 `内容`。


> [!warning]
> 警告 `内容`。


> [!caution]
> 注意 `内容`。


> [!caution]- 这是一个**可折叠**的标注框
> 注意内容。


> [!note]+ 这是一个**可折叠**的标注框
> 注意内容。


## 全功能代码块


由 :link[astro-expressive-code]{id=https://github.com/expressive-code/expressive-code/tree/main/packages/astro-expressive-code} 支持，并集成 [@expressive-code/plugin-collapsible-sections](https://expressive-code.com/plugins/collapsible-sections/) 和 [@expressive-code/plugin-line-numbers](https://expressive-code.com/plugins/line-numbers/) 插件，为代码块添加样式和额外功能。


如需自定义代码块主题或功能，请在查阅 :link[Expressive Code 配置文档]{id=https://expressive-code.com/reference/configuration/} 后，修改项目根目录下的 `ec.config.mjs` 文件，例如：[更换主题](https://expressive-code.com/guides/themes/#using-bundled-themes)、[启用自动换行](https://expressive-code.com/key-features/word-wrap/#wrap) 或 [切换行号显示](https://expressive-code.com/plugins/line-numbers/#showlinenumbers)。


以下是功能快速预览，详细说明请查阅 [详细指南](https://expressive-code.com/key-features/syntax-highlighting/)。


#### 语法高亮


` ` `js title='example.md'
console.log('This code is syntax highlighted!')
` ` `


##### 代码编辑器框架


` ` `js title="my-test-file.js"
// 使用 `title="my-test-file.js"`console.log('Title attribute example')` ` `


` ` `ts
// src/content/index.ts
// 使用 `// src/content/index.ts`console.log('File name comment example')` ` `


##### 终端框架


` ` `bash
echo "此终端框架没有标题"
` ` `


` ` `powershell title="PowerShell terminal example"
Write-Output "这个有标题！"
` ` `


##### 标记整行与行范围


` ` `js {1, 4, 7-8}
// 第 1 行 - 按行号指定
// 第 2 行
// 第 3 行
// 第 4 行 - 按行号指定
// 第 5 行
// 第 6 行
// 第 7 行 - 按范围 "7-8" 指定
// 第 8 行 - 按范围 "7-8" 指定
` ` `


##### 选择行标记类型（mark、ins、del）


` ` `js title="line-markers.js" del={2} ins={3-4} {6}
function demo() {
console.log('此行标记为已删除')
// 此行及下一行标记为已插入
console.log('这是第二行已插入的内容')


return '此行使用默认中性标记类型'
}
` ` `


##### 使用类 diff 语法


` ` `diff
+此行将标记为已插入
-此行将标记为已删除
这是普通行
` ` `


` ` `diff lang="js"
function thisIsJavaScript() {
// 整个代码块以 JavaScript 高亮显示，
// 同时仍可添加 diff 标记！


- console.log('待删除的旧代码')


* console.log('全新的代码！')
  }
  ` ` `


##### 按代码块配置自动换行


` ` `js wrap
// 启用换行的示例
function getLongString() {
  return 'This is a very long string that will most probably not fit into the available space unless the container is extremely wide'
}
` ` `


` ` `js wrap=false
// 禁用换行的示例
function getLongString() {
  return 'This is a very long string that will most probably not fit into the available space unless the container is extremely wide'
}
` ` `


##### 可折叠区域


` ` `js collapse={1-5, 12-14, 21-24}
// 所有样板初始化代码将被折叠
import { someBoilerplateEngine } from '@example/some-boilerplate'
import { evenMoreBoilerplate } from '@example/even-more-boilerplate'


const engine = someBoilerplateEngine(evenMoreBoilerplate())


// 此部分代码默认可见
engine.doSomething(1, 2, 3, calcFn)


function calcFn() {
const a = 1
const b = 2
const c = a + b
console.log(`Calculation result:  +  = `)
return c
}


engine.closeConnection()
engine.freeMemory()
engine.shutdown({ reason: 'End of example boilerplate code' })
` ` `


##### 按代码块显示行号


` ` `js showLineNumbers
// 此代码块将显示行号
console.log('来自第 2 行的问候！')
console.log('我在第 3 行')
` ` `


` ` `js showLineNumbers startLineNumber=5
// 更改起始行号
console.log('来自第 5 行的问候！')
console.log('我在第 6 行')
` ` `


## 图片说明与链接


使用 :link[remark-directive-sugar]{#lin-stephanie/remark-directive-sugar .github} 中的 [`:::image`](https://github.com/lin-stephanie/remark-directive-sugar?tab=readme-ov-file#image-) 指令，将图片包裹在容器中以支持说明文字、可点击链接等功能。可通过 `plugins/index.ts` 中的 `image` 选项进行自定义，样式写在 `src/styles/pro.css` 的 `/* :::image */` 部分。


### image-figure


` ` `md title=':::image-figure.md'
:::image-figure[这是带有 **Figcaption** 和 `<figure>` 属性的示例]{style="text-align:center;color:orange"}
![](assets/cover.png)
:::


:::image-figure[这是带有 **figcaption** 和 `<img>` 属性的示例。]
![](assets/cover.png)(style: width:600px;)
:::


<!-- 💡 使用 `(class:no-zoom)` 禁用缩放 -->


:::image-figure[这是带有 `class:no-zoom` 的示例。]
![](assets/cover.png)(class:no-zoom)
:::


<!-- 💡 若没有 `[caption]`，将使用 `[alt]` 作为 figcaption。 -->


:::image-figure
![若未设置 `[caption]`，alt 文本将作为 figcaption 使用。](assets/cover.png)
:::


<!-- ❌ 若 figcaption 没有可用文本，则无法生效。 -->


` ` `


> [!warning]
> 直接设置图片的 `width` 属性可能导致模糊。[了解更多](https://github.com/Dnzzk2/Litos/discussions/17)


### image-a


` ` `md title=':::image-a.md'
:::image-a{href="https://github.com/Dnzzk2/Litos"}
![OG image](assets/cover.png)
:::


<!-- ❌ 未提供外部链接时无法生效。-->


:::image-a
![OG image](assets/cover.png)
:::
` ` `


### image-figure-polaroid


` ` `md title=':::image-figure-polaroid.md'
:::::image-div-polaroid
:::image-figure-polaroid[这是带有 **figcaption** 和 `<img>` 属性的示例。]
![OG image](assets/cover.png)
:::
:::::


:::::image-div-polaroid
:::image-figure-polaroid{style="width:500px;"}
![OG image](assets/cover.png)
:::
:::::
` ` `


## GitHub 卡片


感谢 :link[oopsunix]{#@oopsunix} 的贡献！


` ` `md title=':::github-card.md'
::github{repo="Dnzzk2/Litos"}
` ` `


## 视频嵌入


使用 :link[remark-directive-sugar]{id=lin-stephanie/remark-directive-sugar class=github} 中的 [`::video`](https://github.com/lin-stephanie/remark-directive-sugar?tab=readme-ov-file#video-) 指令，统一嵌入不同平台的视频。


` ` `md title='example.md'


<!-- 嵌入 YouTube 视频 -->


::video-youtube{#gxBkghlglTg}


<!-- 嵌入 Bilibili 视频，并自定义 `title` 属性 -->


::video-bilibili[自定义标题]{id=BV1MC4y1c7Kv}


<!-- 嵌入 Vimeo 视频，使用 `no-scale` 类禁用缩放 -->


::video-vimeo{id=912831806 class='no-scale'}


<!-- 嵌入自定义视频 URL（必须使用 `id`，不能用 `#`） -->


::video{id=https://www.youtube-nocookie.com/embed/gxBkghlglTg}
` ` `


## 样式链接（`:link`）


使用 :link[remark-directive-sugar]{id=lin-stephanie/remark-directive-sugar class=github} 中的 [`:link`](https://github.com/lin-stephanie/remark-directive-sugar?tab=readme-ov-file#link) 指令，为 GitHub、npm 或自定义 URL 添加带头像或图标的链接。


**链接到 GitHub 用户或组织（在 `id` 前加 `@`）​**


- **示例 1**：`:link[Dnzzk2]{#@Dnzzk2}` 链接到项目维护者的 GitHub 主页，如 :link[Dnzzk2]{#@Dnzzk2}。
- **示例 2**：`:link[Vite]{id=@vitejs}` 链接到 :link[Vite]{id=@vitejs} 组织的 GitHub 主页。
- **示例 3**：`:link{#@Dnzzk2 tab=repositories}` 直接链接到该用户的仓库标签页，如 :link{#@Dnzzk2 tab=repositories}。有效 `tab` 选项：`'repositories'`、`'projects'`、`'packages'`、`'stars'`、`'sponsoring'`、`'sponsors'`。
- **示例 4**：`:link{#@vitejs tab=org-people}` 链接到组织成员页面，如 :link{#@vitejs tab=org-people}。有效 `tab` 选项：`'org-repositories'`、`'org-projects'`、`'org-packages'`、`'org-sponsoring'`、`'org-people'`。


**链接到 GitHub 仓库**


- **示例 5**：`:link[Astro]{#withastro/astro}` 创建指向 :link[Astro]{#withastro/astro} 仓库的链接。


**链接到 npm 包**


- **示例 6**：`:link{#remark-directive-sugar}` 链接到 :link{#remark-directive-sugar} 的 npm 主页。
- **示例 7**：`:link{id=remark-directive-sugar tab=dependencies}` 链接到 npm 上的 :link{id=remark-directive-sugar tab=dependencies} 页面。有效 `tab` 选项：`'readme'`、`'code'`、`'dependencies'`、`'dependents'`、`'versions'`。


**链接到自定义 URL（必须使用 `id`，不能用 `#`）​**


- **示例 8**：`:link{id=https://developer.mozilla.org/en-US/docs/Web/JavaScript}` 创建指向 :link{id=https://developer.mozilla.org/en-US/docs/Web/JavaScript} 的外部链接。
- **示例 9**：`:link[Google]{id=https://www.google.com/}` 创建指向 :link[Google]{id=https://www.google.com/} 的外部链接。


**自定义**


- **示例 10**：`:link[Vite]{id=@vitejs url=https://vite.dev/}` 将链接指向 `https://vite.dev/`，如 :link[Vite]{id=@vitejs url=https://vite.dev/}。
- **示例 11**：`:link[Vite]{id=@vitejs img=https://vitejs.dev/logo.svg}` 显示自定义 Logo，如 :link[Vite]{id=@vitejs img=https://vitejs.dev/logo.svg}。
- **示例 12**：`:link{id=Dnzzk2/Litos class=github}` 使用 `class=github` 覆盖默认样式，如 :link{id=Dnzzk2/Litos class=github}。
- **示例 13**：`:link[Litos Themes]{id=https://github.com/Dnzzk2/Litos img=...}` 完全自定义一个链接，如 :link[Litos Themes]{id=https://github.com/Dnzzk2/Litos img=https://litos.vercel.app/favicon.ico}。


## 徽章（Badges）


使用 :link[remark-directive-sugar]{id=lin-stephanie/remark-directive-sugar class=github} 中的 [`:badge`](https://github.com/lin-stephanie/remark-directive-sugar?tab=readme-ov-file#badge-) 指令，显示状态或分类等小型信息片段。


主题预定义徽章如下，可通过 `plugins/index.ts` 中的 `badge` 选项自定义，样式写在 `src/styles/pro.css` 的 `/* :badge */` 部分：


- `badge-n`：:badge-n


也可直接使用 `:badge[文字]{属性}` 自定义外观。例如：`:badge[ISSUE]{style="background-color: #bef264"}` 将显示为 :badge[ISSUE]{style="background-color: #bef264"}。若未指定颜色，默认外观如 :badge[This] 所示。


## 详情折叠（Details Dropdown）


` ` `md title=':::details.md'
:::details
::summary[详情折叠]


- 列表项 1
- 列表项 2
- 列表项 3
- 列表项 4
  :::
  ` ` `


此外，它也支持类似 [remark-directive 示例](https://github.com/remarkjs/remark-directive?tab=readme-ov-file#use) 中的用法。

Comments