编辑Wiki页面

现在您已在本地搭建好Wiki环境，可以直接在设备上编辑文件。如果您不熟悉VSCode操作，微软官方提供了一些优质教学视频点击查看。

为了让页面更美观，我们提供了丰富的工具来高亮章节、插入组件、添加图片等功能！

页面结构

每个页面由两部分组成：前置元数据（frontmatter）和正文内容。

前置元数据用于记录文章的关键信息：

---
title: 精彩的页面标题
description: 完成您的首次贡献！
license: true
mentions:
    - 用户名
---

这里是正文内容！

前置元数据

字段	必填	默认值	说明
`title`	✔️	无	页面标题，将作为一级标题显示在正文前，也会在链接嵌入时展示
`description`	✔️	无	页面描述，会在链接嵌入时显示。禁止包含 `:` 和 `"` 符号
`category`	❌	无	侧边栏分类名称。可用分类列表见各版块的`index.md`文件
`tags`	❌	`[]`	显示在页面顶部的标签列表。部分标签（如"guide"或"info"）会显示在侧边栏。若页面所属分类已包含标签含义，则无需重复添加（例如"教程"分类下的页面不需再添加"guide"标签）
`nav_order`	❌	无	侧边栏文章排序序号。数值越小排名越靠前，所有带序号的条目会显示在无序号条目之前
`outline_depth`	❌	`3`	页面大纲显示的最大标题层级。可减少默认值隐藏重复标题，或增加层级便于导航
`show_contributors`	❌	`true`	是否在页面末尾显示贡献者名单
`show_edit_link`	❌	`true`	是否显示指向GitHub仓库的编辑链接
`show_outline`	❌	`true`	是否生成标题导航大纲
`hidden`	❌	`false`	是否在侧边栏隐藏页面（仍可通过直接链接访问）
`license`	✔️	无	页面内容授权方式。可以是许可证ID字符串（如`MIT`），或是定义`main`和`code`分别授权的对象
`mentions`	✔️	`[]`	参与本页编辑的GitHub用户名。请确保添加您的贡献记录！

标题是必填项，它将显示在左侧导航栏。虽然贡献者名单不是必须的，但让读者知道文章作者是件很棒的事！

可用分类

各版块的可用分类列表可在对应index.md文件中查看，包含颜色和排序信息。您也可以在此添加新分类。

以下是多数版块通用的分类（其他分类请查看侧边栏）：

通用
教程
文档

可用标签

标签定义在docs/.vitepress/tags.ts文件中。如需新增标签，请在此文件添加。

现有标签列表如下：

beginner
beta
deprecated
easy
experimental
expert
function
guide
help
info
intermediate
method
outdated
scripting

正文内容

前置元数据之后是Markdown格式的正文内容，可使用自定义组件增强页面表现力。

这些组件可添加按钮、折叠内容、代码块等元素。虽然支持HTML，但仅建议高级用户使用。

页面标题

新手常见错误是在正文中重复添加一级标题。请注意前置元数据中的标题会自动显示在页面顶部，单个页面出现多个一级标题是无效结构。

Wiki扩展包

某些教程需要配套模板/示例包，我们使用独立GitHub仓库维护：wiki-addon。请将您的资源包提交至此，便于统一维护更新。

本地预览Wiki

编辑时很难直观感受最终效果。您可以在本地运行Wiki网站：

在VSCode顶部菜单栏点击终端 > 新建终端

安装依赖

首次本地预览时需运行npm install完成环境配置

输入npm run dev并回车，加载完成后会显示：

按住Ctrl键点击http://localhost:5173/，浏览器将打开本地Wiki。之后每次保存文件都会自动刷新页面。

构建页面预览

上述方法展示的是开发视图。某些错误仅在构建时才会出现。

构建过程会将所有Markdown编译为HTML页面。如需完整构建，请改用npm run build命令。

TIP

npm run build会编译全部页面（包括体积巨大的页面）。如果未编辑以下文件，建议使用npm run fastbuild跳过这些页面的构建：

json

[
    "entities/vanilla-usage-components.md",
    "entities/vanilla-usage-spawn-rules.md",
    "entities/vuc-full.md",
    "entities/vusr-full.md"
]

构建完成后运行npm run preview，打开终端显示的链接即可查看。

Markdown使用指南

本Wiki使用强大的Markdown文本格式化语法。完整语法请参考Markdown指南，以下是重点注意事项：

内容容器

容器用于突出重要信息，共有四种类型：info、tip、warning和danger。

使用三个冒号声明容器类型，内容结束后再用三个冒号闭合：

:::info
这里是提示信息
:::

:::tip
实用小技巧
:::

:::warning
注意事项
:::

:::danger
危险操作警告
:::

:::details
补充说明（不建议使用）
:::

INFO

这里是提示信息

TIP

实用小技巧

WARNING

注意事项

DANGER

危险操作警告

Details

补充说明（不建议使用）

details容器样式未优化，不建议使用。

可为容器添加标题：

:::danger 紧急停止！
危险操作区域
:::

紧急停止！

危险操作区域

链接

引用外部网站（如微软文档）时可以使用链接。

Markdown链接有两种形式：

直接显示URL：https://bedrock.dev
显示自定义文本：点击访问

外部链接

完整URL包含https前缀：

[官方创作者文档](https://learn.microsoft.com/minecraft/creator/)

官方创作者文档

内部链接

使用相对路径链接Wiki内其他页面：

[跳转到贡献指南](/contribute)

跳转到贡献指南

[JSON数组](/guide/understanding-json#arrays)

JSON数组

[跳转到Markdown章节](#working-with-markdown)

跳转到Markdown章节

链接路径参照docs文件夹结构：

根目录页面：/pagename
子目录页面：/folder/pagename

WARNING

禁止使用包含bedrock.8aka.org的绝对链接！

列表

无序列表

普通项目符号列表：

-   项目一
-   项目二
-   项目三

项目一
项目二
项目三

有序列表

带序号列表：

1.  第一项
2.  第二项
3.  第三项

第一项
第二项
第三项

任务列表

带复选框的列表（方括号内加x表示完成）：

-   [x] 已完成
-   [ ] 未完成
-   [x] 已完成

已完成
未完成
已完成

组件使用指南

本Wiki采用特殊Vue组件，可添加按钮、折叠内容、代码块等元素。

代码片段

输入wiki.后按Ctrl+Space可查看组件快捷代码：

强调色

部分组件支持color属性，可选值包括：

red
orange
yellow
green
blue
purple

按钮组件

比普通链接更醒目的可点击按钮：

<Button link="/">
    返回首页
</Button>

返回首页

可指定强调色增强视觉效果：

<Button link="https://youtube.com" color="red">
    YouTube
</Button>

YouTube

属性	必填	类型	说明
link	是	字符串	点击跳转链接。也可用于文件下载（如图片下载需在链接后添加`download`参数）
color	否	强调色	按钮颜色。默认使用Wiki主题色

按钮文本写在两个Button标签之间。

卡片组件

图文结合的可点击卡片：

<Card image="/assets/images/homepage/wikilogo.png" title="示例标题" link="https://google.com">

这里是_卡片内容_。

</Card>

示例标题

这里是_卡片内容_。

属性	必填	类型	说明
image	是	字符串	标题左侧显示的图片路径
title	是	字符串	内容区上方的标题
link	否	字符串	点击标题时的跳转链接

请勿过度使用，以免分散读者注意力。

卡片网格

多卡片网格布局容器：

<CardGrid>
<Card image="/assets/images/homepage/wikilogo.png" title="标题1" link="https://google.com">

内容区一

</Card>
<Card image="/assets/images/homepage/wikilogo.png" title="标题2" link="https://google.com">

内容区二

</Card>
</CardGrid>

标题1

内容区一

标题2

内容区二

代码头

为代码块添加文件路径说明：

json

<CodeHeader>BP/blocks/example.json</CodeHeader>

```json
{
    "示例": "JSON结构"
}
```

BP/blocks/example.json

json

{
    "示例": "JSON结构"
}

文件路径规范：

行为包文件以BP/开头
资源包文件以RP/开头

组件下方必须紧跟代码块。

文件夹视图

展示文件目录结构：

<FolderView :paths="[
    'com.mojang/development_resource_packs/guide_RP/texts/en_US.lang',
    'com.mojang/development_resource_packs/guide_RP/manifest.json'
]" />

- - - - 🈵en_US.lang
    - 📝manifest.json

属性	必填	类型	说明
paths	是	字符串数组	要显示的文件路径列表

注意路径列表内不能有空行！

标签组件

彩色小标签：

<Label color="green">
    标签文本
</Label>

标签文本

属性	必填	类型	说明
color	是	强调色	标签背景色

请勿过度使用。

折叠内容

可折叠隐藏的内容区块：

<Spoiler title="折叠标题">

隐藏内容一

隐藏内容二

</Spoiler>

折叠标题

隐藏内容一

隐藏内容二

属性	必填	类型	说明
title	是	字符串	折叠按钮显示的标题

注意内容与标签之间保留空行！

标签组件

与页面顶部标签样式一致的组件：

<Tag name="beginner" />

beginner

属性	必填	类型	说明
name	是	标签名	要显示的标签

Wiki图片

标准Markdown图片语法：![](/assets/images/...)

增强版图片组件支持更多参数：

<WikiImage
    src="/assets/images/homepage/wikilogo.png"
    alt="替代文本"
    caption="图片说明"
    width="420"
    pixelated
/>

图片说明

属性	必填	类型	说明
src	是	字符串	图片路径
alt	是	字符串	图片加载失败时显示的替代文本
caption	否	字符串	图片下方的说明文字
width	否	字符串	图片宽度（仅设置宽度时高度自动缩放）
height	否	字符串	图片高度（仅设置高度时宽度自动缩放）
pixelated	否	布尔值	是否启用像素化渲染

YouTube嵌入

通过视频ID嵌入YouTube内容：

<YouTubeEmbed id="dQw4w9WgXcQ" />

属性	必填	类型	说明
id	是	字符串	YouTube视频ID

换行规范

组件前后必须保留空行！

错误示范：

-   项目一
-   项目二
<CodeHeader>BP/blocks/example.json</CodeHeader>
```json
{
    "示例": "JSON"
}
```

正确示范：

-   项目一
-   项目二

<CodeHeader>BP/blocks/example.json</CodeHeader>

```json
{
    "示例": "JSON"
}
```

格式指南

统一的格式规范能提升Wiki阅读体验。

通用规则

包名、文件夹命名等请参考样式指南

标题大小写

页面标题和各级标题需采用标题式大小写：

多数单词首字母大写
冠词(a/an/the)、并列连词(and/but/or)、介词(in/on/at/of/to)通常小写，除非：
- 作为标题首尾单词
- 构成特定名词（如add-on）

示例：

欢迎来到Wiki！
您的第一个附加包
工作原理

标题层级

禁止使用一级标题（页面顶部已自动生成）
避免使用超过四级的标题（侧边栏仅显示二级标题）
采用标题式大小写
禁止在标题中使用冒号

正确示例：

## 示例页面（正确）
# 示例页面（错误）
### 子章节（正确）
###### 子章节（错误）
## 我的文章（正确）
## 我的：文章（错误）
## 后续步骤（正确）
## 后续步骤：（错误）

JSON代码规范

尽量使用代码头组件
完整展开JSON结构提升可读性（格式化工具）
- 但`.geo

贡献者

编辑编辑Wiki页面

编辑Wiki页面

页面结构 ​

前置元数据 ​

可用分类 ​

可用标签 ​

正文内容 ​

Wiki扩展包 ​

本地预览Wiki ​

构建页面预览 ​

Markdown使用指南 ​

内容容器 ​

链接 ​

外部链接 ​

内部链接 ​

列表 ​

无序列表 ​

有序列表 ​

任务列表 ​

组件使用指南 ​

强调色 ​

按钮组件 ​

卡片组件 ​

卡片网格 ​

代码头 ​

文件夹视图 ​

标签组件 ​

折叠内容 ​

标签组件 ​

Wiki图片 ​

YouTube嵌入 ​

换行规范 ​

格式指南 ​

通用规则 ​

标题大小写 ​

标题层级 ​

JSON代码规范 ​

贡献者

页面结构

前置元数据

可用分类

可用标签

正文内容

Wiki扩展包

本地预览Wiki

构建页面预览

Markdown使用指南

内容容器

链接

外部链接

内部链接

列表

无序列表

有序列表

任务列表

组件使用指南

强调色

按钮组件

卡片组件

卡片网格

代码头

文件夹视图

标签组件

折叠内容

标签组件

Wiki图片

YouTube嵌入

换行规范

格式指南

通用规则

标题大小写

标题层级

JSON代码规范