文档站格式

本页面用于原初服务器文档规范 VitePress 项目中 Markdown、VitePress 特有格式和 Vue 组件的写法，方便其他编辑者快速上手。

一、Markdown 基础格式

1.1 标题层级

使用 # 表示标题，一级到六级对应不同层级。

# 一级标题
## 二级标题
### 三级标题
#### 四级标题
##### 五级标题
###### 六级标题

建议

建议文档中最多使用到三级标题，保持层次清晰。

1.2 文本样式

**粗体文字**
*斜体文字*
***粗斜体文字***
~~删除线文字~~

效果示例：

粗体
斜体
粗斜体
~~删除线~~

1.3 列表

无序列表：

- 第一项
- 第二项
  - 嵌套项 A
  - 嵌套项 B
- 第三项

有序列表：

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

1.4 链接与图片

链接：

[链接文字](https://example.com)

图片：

![图片描述](图片路径.png)

路径说明

内部图片建议放在同一目录或子目录下
图片路径相对于当前 Markdown 文件位置

1.5 代码块

行内代码：

这是一段 `行内代码` 示例。

多行代码块：

```bash
npm install vitepress
```

指定语言：

```javascript
const hello = 'world'
console.log(hello)
```

常用语言标识：md、bash、javascript、python、json、yaml、html、css、typescript、java、cpp、go、rust、sql 等。

1.6 引用块

> 这是一个引用块
> 可以多行
> 支持嵌套

这是一个引用块示例。

1.7 水平线

---

效果：

1.8 表格

| 表头1 | 表头2 | 表头3 |
| :--- | :---: | ---: |
| 左对齐 | 居中 | 右对齐 |
| 内容1 | 内容2 | 内容3 |

表头1	表头2	表头3
左对齐	居中	右对齐
内容1	内容2	内容3

二、VitePress 特有格式

2.1 自定义容器

VitePress 支持四种自定义容器类型：

::: info
这是信息容器。
:::

::: tip
这是提示容器。
:::

::: warning
这是警告容器。
:::

::: danger
这是危险容器。
:::

::: details
这是折叠详情容器。
:::

效果示例：

INFO

这是信息容器。

TIP

这是提示容器。

WARNING

这是警告容器。

DANGER

这是危险容器。

Details

这是折叠详情容器。

2.2 代码块高亮与行号

行高亮：

```javascript {2,4-6}
const a = 1
const b = 2  // 高亮此行
const c = 3
const d = 4  // 高亮此行
const e = 5  // 高亮此行
const f = 6
```

行号显示：

```javascript showLineNumbers
const hello = 'world'
console.log(hello)
```

2.3 代码块文件名标注

```bash filename="终端命令"
npm install
```

2.4 可复制文本

```mdtxt
可复制的文本内容
```

2.5 Emoji 使用

使用 :emoji: 格式或直接输入 Emoji：

:smile: :rocket: :warning: :bulb:

常用 Emoji 速查：

用途	Emoji	写法
提示	💡	`:bulb:`
警告	⚠️	`:warning:`
重要	❗	`:exclamation:`
书籍	📖	`:book:`
工具	🛠️	`:hammer_and_wrench:`
注意	❗	`:exclamation:`
开始	🏁	`:checkered_flag:`
建筑	🏗️	`:construction:`
机器	🏭	`:factory:`
地图	🗺️	`:map:`

2.6 链接格式

内部链接（跳转本站点其他页面）：

[新人指南](/Primaryuan/ch1/NewPlayer)

外部链接（新窗口打开）：

[原初官网](https://primaryuan.top:2021/)

带图标的外链示例（VitePress 默认支持）：

[GitHub 仓库](https://github.com/brokeyuan)

2.7 目录大纲

在 config.mts 中配置：

javascript

export default defineConfig({
  themeConfig: {
    outline: [2, 3]  // 显示二级和三级标题
  }
})

在 Markdown 中使用：

[[toc]]

三、项目 Vue 组件说明

本项目已注册以下全局组件，可在任意 Markdown 文件中直接使用。

3.1 RepoCard - 仓库卡片

Repo 卡片组件用于显示 GitHub / Gitee 仓库信息。

使用方法：

<RepoCard repo="pengzhanbo/vuepress-theme-plume" />

Props：

属性	类型	默认值	说明
`repo`	`string`	`''`	仓库路径，如 `用户名/仓库名`
`fullname`	`boolean`	`false`	是否显示完整仓库名
`provider`	`'github' \| 'gitee'`	`'github'`	仓库来源平台

示例：

<!-- GitHub 仓库 -->
<RepoCard repo="brokeyuan/primaryuan-doc" />

<!-- Gitee 仓库 -->
<RepoCard repo="gitee-user/repo-name" provider="gitee" />

<!-- 显示完整名称 -->
<RepoCard repo="pengzhanbo/vuepress-theme-plume" :fullname="true" />

3.2 LinkCard - 链接卡片

链接卡片组件，用于展示带有图标、标题和描述的链接。

使用方法：

<LinkCard title="标题" href="https://example.com" description="描述文字" icon="图标路径.png" />

Props：

属性	类型	默认值	说明
`title`	`string`	`''`	卡片标题
`href`	`string`	`''`	跳转链接
`description`	`string`	`''`	描述文字
`icon`	`string \| { svg: string }`	`undefined`	图标（图片路径或 SVG 对象）
`target`	`string`	`'_blank'`	链接打开方式

示例：

<!-- 基础用法 -->
<LinkCard
  title="原初官网"
  href="https://primaryuan.top:2021/"
  description="原初服务器官方网站"
/>

<!-- 带图片图标 -->
<LinkCard
  title="GitHub 仓库"
  href="https://github.com/brokeyuan"
  description="查看更多开源项目"
  icon="/logo.svg"
/>

<!-- 使用插槽 -->
<LinkCard title="标题" href="https://example.com">
  <p>自定义描述内容</p>
  <ul>
    <li>特性一</li>
    <li>特性二</li>
  </ul>
</LinkCard>

3.3 Linkcard2 - 横向链接卡片

另一种横向排列的链接卡片样式，Logo 在左侧，文字在右侧。

使用方法：

<Linkcard2
  title="标题"
  url="https://example.com"
  description="描述文字"
  logo="/logo.svg"
/>

Props：

属性	类型	默认值	说明
`title`	`string`	`''`	标题文字
`url`	`string`	`''`	跳转链接
`description`	`string`	`''`	描述文字
`logo`	`string`	`''`	Logo 图片路径

3.4 ImageCard - 图片卡片

概述

使用 <ImageCard> 组件在页面中显示图片卡片。

图片卡片有别于 markdown 的普通插入图片方式，它展示与图片相关的更多信息，包括标题、描述、作者、链接等。适用于如摄影作品、设计作品、宣传海报等场景。

图片组件 Props 定义

Props：

属性	类型	默认值	说明
`image`	`string`	`''`	图片路径（必填）
`title`	`string`	`''`	图片标题
`description`	`string`	`''`	图片描述信息
`href`	`string`	`''`	点击图片标题后的跳转链接
`author`	`string`	`''`	图片作者名称
`date`	`string \| Date \| number`	`undefined`	图片创作日期
`width`	`string \| number`	`undefined`	图片宽度
`center`	`boolean`	`false`	当图片宽度不满屏时，是否居中显示

示例

输入：

<ImageCard
  image="https://cn.bing.com/th?id=OHR.AlfanzinaLighthouse_ZH-CN9704515669_1920x1080.webp"
  title="阿尔凡齐纳灯塔，阿尔加维，葡萄牙"
  description="今天照片中的灯塔位于葡萄牙南部海岸阿尔加维的卡沃埃罗。阿尔凡齐纳灯塔建于1919年，照耀着大海，帮助船只在该地区周围危险的水域航行。这座灯塔是著名的旅游胜地，同时也是该地区与海洋紧密联系的象征。如果你有幸住在灯塔附近，那么本周末就是拜访灯塔的最佳时机。"
  href="/"
  author="Andreas Kunz"
  date="2024/08/16"
/>

输出：

阿尔凡齐纳灯塔，阿尔加维，葡萄牙

Andreas Kunz | 2024年8月16日

今天照片中的灯塔位于葡萄牙南部海岸阿尔加维的卡沃埃罗。阿尔凡齐纳灯塔建于1919年，照耀着大海，帮助船只在该地区周围危险的水域航行。这座灯塔是著名的旅游胜地，同时也是该地区与海洋紧密联系的象征。如果你有幸住在灯塔附近，那么本周末就是拜访灯塔的最佳时机。

还可以放到 <CardGrid> 组件中。

输入：

<CardGrid>
  <ImageCard
    image="https://cn.bing.com/th?id=OHR.AlfanzinaLighthouse_ZH-CN9704515669_1920x1080.webp"
    title="阿尔凡齐纳灯塔，阿尔加维，葡萄牙"
    description="..."
    href="/"
    author="Andreas Kunz"
    date="2024/08/16"
  />
  <ImageCard
    image="https://cn.bing.com/th?id=OHR.AlfanzinaLighthouse_ZH-CN9704515669_1920x1080.webp"
    title="阿尔凡齐纳灯塔，阿尔加维，葡萄牙"
    description="..."
    href="/"
    author="Andreas Kunz"
    date="2024/08/16"
  />
</CardGrid>

输出：

阿尔凡齐纳灯塔，阿尔加维，葡萄牙

Andreas Kunz | 2024年8月16日

...

阿尔凡齐纳灯塔，阿尔加维，葡萄牙

Andreas Kunz | 2024年8月16日

...

3.5 CardGrid - 卡片网格

卡片网格组件，用于将多个卡片排成网格布局。

Props：

属性	类型	默认值	说明
`cols`	`number \| { sm?, md?, lg? }`	`2`	网格列数，支持响应式配置

示例：

<!-- 两列布局 -->
<CardGrid>
  <LinkCard title="卡片标题" href="/" />
  <LinkCard icon="twemoji:astonished-face" title="卡片标题" href="/" />
</CardGrid>

卡片标题

3.6 MNavLinks - 导航链接组

导航链接组组件，用于展示一组导航链接，支持 badge 标签显示状态。

使用方法：

<MNavLinks
  title="相关链接"
  :items="[
    { text: '新人指南', link: '/Primaryuan/ch1/NewPlayer' },
    { text: '服规', link: '/Primaryuan/ch2/Rule_Server' },
    { text: '常见问题', link: '/Primaryuan/ch4/FAQ' },
  ]"
/>

Props：

属性	类型	默认值	说明
`title`	`string`	-	分组标题
`noIcon`	`boolean`	`false`	是否隐藏图标
`items`	`NavLink[]`	-	链接列表

NavLink 类型：

属性	类型	说明
`text`	`string`	链接文字
`link`	`string`	链接地址
`icon`	`string \| { svg: string }`	图标（可选）
`desc`	`string`	描述文字（可选）
`badge`	`string \| { text?, type? }`	状态标签（可选）

Badge type 颜色对应（用于表示在线状态）：

type	颜色	建议用途
`tip`	绿色	在线状态
`danger`	红色	离线状态
`warning`	黄色	维护中/警告
`info`	蓝色	一般信息/新功能

带 Badge 的使用示例：

<MNavLinks
  title="游戏服务器状态"
  :items="[
    { 
      text: 'Minecraft 生存服', 
      link: '/Primaryuan/ch2/Introdu_Server',
      badge: { text: '在线', type: 'tip' }
    },
    { 
      text: 'CS2 服务器', 
      link: '/Primaryuan/ch4/Cs2',
      badge: { text: '离线', type: 'danger' }
    },
    { 
      text: 'Teamspeak 语音', 
      link: '/Primaryuan/ch4/Teamspeak',
      badge: { text: '维护中', type: 'warning' }
    },
    { 
      text: '小游戏服', 
      link: '/Primaryuan/ch3/Games',
      badge: 'info'
    }
  ]"
/>

在线状态约定

在线：使用 type: 'tip'（绿色）
离线：使用 type: 'danger'（红色）
维护中：使用 type: 'warning'（黄色）

3.7 MCServerStatus - MC 服务器在线状态

MC 服务器在线状态组件，用于实时展示 Minecraft 服务器的在线状态、玩家数量和在线玩家列表。

使用方法：

<MCServerStatus host="primaryuan.top:65535" />

Props：

属性	类型	默认值	说明
`host`	`string`	`''`	服务器地址和端口，如 `primaryuan.top:65535`（必填）
`refreshInterval`	`number`	`3000`	自动刷新间隔（毫秒），设置为 `0` 可禁用自动刷新

示例：

<!-- 基础用法 -->
<MCServerStatus host="primaryuan.top:65535" />

<!-- 自定义刷新间隔（5秒） -->
<MCServerStatus host="primaryuan.top:65535" :refreshInterval="5000" />

<!-- 禁用自动刷新 -->
<MCServerStatus host="primaryuan.top:65535" :refreshInterval="0" />

显示内容：

服务器状态（在线/离线）
服务器地址
游戏版本
在线人数 / 最大人数
延迟（毫秒）
在线玩家列表
服务器 MOTD（消息）

数据源：

该组件使用 MOTD站获取服务器状态：

四、Vue 组件编写规范

以下是项目中 Vue 组件的编写规范，供开发新组件时参考。

4.1 组件基本结构

vue

<script setup lang="ts">
import { ref, computed } from 'vue'

// Props 定义
interface Props {
  title?: string
  count?: number
}

const props = withDefaults(defineProps<Props>(), {
  title: '',
  count: 0,
})

// 响应式数据
const message = ref('Hello')

// 计算属性
const doubled = computed(() => props.count * 2)
</script>

<template>
  <div class="component">
    <h2>{{ props.title }}</h2>
    <p>{{ message }} - {{ doubled }}</p>
  </div>
</template>

<style scoped>
.component {
  padding: 16px;
  border-radius: 8px;
}
</style>

4.2 Props 定义方式

vue

<script setup lang="ts">
interface Props {
  image: string
  title?: string
  description?: string
  href?: string
  width?: string | number
  center?: boolean
}

const props = withDefaults(defineProps<Props>(), {
  title: '',
  description: '',
  href: '',
  width: undefined,
  center: false,
})
</script>

4.3 插槽（Slot）使用

默认插槽：

vue

<template>
  <div class="card">
    <slot />
  </div>
</template>

命名插槽：

vue

<template>
  <div class="card">
    <slot name="header" />
    <slot name="content" />
    <slot name="footer" />
  </div>
</template>

使用插槽：

vue

<MyCard>
  <template #header>标题</template>
  <template #content>内容</template>
  <template #footer>页脚</template>
</MyCard>

4.4 条件渲染与循环

vue

<template>
  <div>
    <p v-if="props.title">{{ props.title }}</p>
    <ul>
      <li v-for="(item, index) in items" :key="index">
        {{ item }}
      </li>
    </ul>
  </div>
</template>

<script setup lang="ts">
const items = ref(['苹果', '香蕉', '橙子'])
</script>

4.5 样式 scoped

vue

<style scoped>
/* scoped 确保样式仅在当前组件内生效 */
.container {
  margin: 16px 0;
}

.title {
  font-size: 18px;
  font-weight: 600;
}

/* 深度选择器，用于修改子组件样式 */
:deep(.child-class) {
  color: red;
}
</style>

4.6 响应式数据与计算属性

vue

<script setup lang="ts">
import { ref, computed, watch } from 'vue'

// 响应式引用
const count = ref(0)
const name = ref('World')

// 计算属性
const greeting = computed(() => {
  return `Hello, ${name.value}! Count: ${count.value}`
})

// 监听器
watch(count, (newVal, oldVal) => {
  console.log(`count changed from ${oldVal} to ${newVal}`)
})

// 方法
function increment() {
  count.value++
}
</script>

4.7 组件注册

新建组件后，在 docs/.vitepress/theme/index.ts 中注册：

typescript

import MyComponent from "./components/MyComponent.vue"

export default {
  extends: DefaultTheme,
  enhanceApp({ app }) {
    app.component('MyComponent', MyComponent)
  }
}

注册后即可在 Markdown 文件中直接使用 <MyComponent />。

四、项目通用规范

4.1 文件命名

Markdown 文件使用有意义的英文或拼音命名
Vue 组件使用 PascalCase 命名（如 ImageCard.vue）
图片文件使用小写字母和短横线组合

4.2 路径规范

Primaryuan/
├── ch1/          # 第一章
│   ├── Start.md
│   └── NewPlayer.md
├── ch2/          # 第二章
│   ├── Building.md
│   └── Machine/  # 机器图片目录
└── readme/       # 格式指南
    └── 格式.md

4.3 图片引用

<!-- 同一目录 -->
![图片描述](图片.png)

<!-- 子目录 -->
![图片描述](Machine/图片.png)

<!-- 父目录 -->
![图片描述](../上一级.png)

文档站格式 ​

一、Markdown 基础格式 ​

1.1 标题层级 ​

1.2 文本样式 ​

1.3 列表 ​

1.4 链接与图片 ​

1.5 代码块 ​

1.6 引用块 ​

1.7 水平线 ​

1.8 表格 ​

二、VitePress 特有格式 ​

2.1 自定义容器 ​

2.2 代码块高亮与行号 ​

2.3 代码块文件名标注 ​

2.4 可复制文本 ​

2.5 Emoji 使用 ​

2.6 链接格式 ​

2.7 目录大纲 ​

三、项目 Vue 组件说明 ​

3.1 RepoCard - 仓库卡片 ​

3.2 LinkCard - 链接卡片 ​

3.3 Linkcard2 - 横向链接卡片 ​

3.4 ImageCard - 图片卡片 ​

概述 ​

图片组件 Props 定义 ​

示例 ​

阿尔凡齐纳灯塔，阿尔加维，葡萄牙

阿尔凡齐纳灯塔，阿尔加维，葡萄牙

阿尔凡齐纳灯塔，阿尔加维，葡萄牙

3.5 CardGrid - 卡片网格 ​

3.6 MNavLinks - 导航链接组 ​

3.7 MCServerStatus - MC 服务器在线状态 ​

四、Vue 组件编写规范 ​

4.1 组件基本结构 ​

4.2 Props 定义方式 ​

4.3 插槽（Slot）使用 ​

4.4 条件渲染与循环 ​

4.5 样式 scoped ​

4.6 响应式数据与计算属性 ​

4.7 组件注册 ​

四、项目通用规范 ​

4.1 文件命名 ​

4.2 路径规范 ​

4.3 图片引用 ​

六、参考资源 ​

文档站格式

一、Markdown 基础格式

1.1 标题层级

1.2 文本样式

1.3 列表

1.4 链接与图片

1.5 代码块

1.6 引用块

1.7 水平线

1.8 表格

二、VitePress 特有格式

2.1 自定义容器

2.2 代码块高亮与行号

2.3 代码块文件名标注

2.4 可复制文本

2.5 Emoji 使用

2.6 链接格式

2.7 目录大纲

三、项目 Vue 组件说明

3.1 RepoCard - 仓库卡片

3.2 LinkCard - 链接卡片

3.3 Linkcard2 - 横向链接卡片

3.4 ImageCard - 图片卡片

概述

图片组件 Props 定义

示例

3.5 CardGrid - 卡片网格

3.6 MNavLinks - 导航链接组

3.7 MCServerStatus - MC 服务器在线状态

四、Vue 组件编写规范

4.1 组件基本结构

4.2 Props 定义方式

4.3 插槽（Slot）使用

4.4 条件渲染与循环

4.5 样式 scoped

4.6 响应式数据与计算属性

4.7 组件注册

四、项目通用规范

4.1 文件命名

4.2 路径规范

4.3 图片引用

六、参考资源