内容编写规范 - ICT学习客栈

文件命名规范

所有内容文件使用 MDX 格式(.mdx)，放置在 src/content/ 对应的集合目录下。文件名建议使用数字前缀控制排序：

CODEtext

01-introduction.mdx02-quickstart.mdx03-advanced.mdx

Front Matter 格式

每篇文章开头必须包含 YAML Front Matter，支持的字段由 baseSchema 定义：

CODEyaml

---title: 文章标题description: 文章描述（用于 SEO 和摘要）lastUpdated: 2026-07-06category: 文章分类tags: [标签1, 标签2, 标签3]brandColor: "#3b82f6"    # 可选，覆盖默认品牌色badge:                     # 可选，标题旁徽章text: "NEW"color: "#ef4444"recommended: true          # 可选，设为推荐文章featured: true             # 可选，设为精选文章author: "作者名"           # 可选statement: "声明文本"      # 可选showCopyright: true        # 可选，显示版权声明---

正文编写

标题层级

CODEmarkdown

## 二级标题（文章内小节）### 三级标题（子话题）#### 四级标题（尽量少用）

代码块 — CodeBlock 组件

项目提供了强大的 CodeBlock 组件，支持 5 种类型：

类型	用途	示例
`code`	编程语言代码	蓝色，多语言语法高亮
`terminal`	终端命令与输出	绿色，`$`/`#` 提示符分色
`network`	网络设备配置	橙色，IP/设备关键字高亮
`config`	配置文件	紫色，显示文件路径
`log`	日志/异常堆栈	红色，日志级别分色

使用前需先 import：

CODEastro

import CodeBlock from '@/components/CodeBlock.astro';

编程语言代码：

CODEmarkdown

<CodeBlock type="code" lang="python" code={`def hello():  print("Hello World")`} />

终端命令：

CODEmarkdown

<CodeBlock type="terminal" code={`$ npm install$ npm run dev`} />

配置文件（带文件路径）：

CODEmarkdown

<CodeBlock type="config" code={`server {  listen 80;  server_name example.com;}`} filePath="/etc/nginx/nginx.conf" label="Nginx" />

链接

内部链接使用相对于 / 的路径：

CODEmarkdown

[配置系统](/manuals/ictstu/03-configuration)[Ansible 入门](/cloud/ansible/01-ansible-lab-setup)

表格

CODEmarkdown

| 列1 | 列2 | 列3 || --- | --- | --- || 数据A | 数据B | 数据C |

图片

将图片放入 public/images/ 目录，引用时使用 /images/xxx.png 路径。

MDX 组件嵌入

在 MDX 中可以直接使用项目内置的 Astro 组件。需要在文件顶部 import 后即可使用。

CODEmdx

---title: 示例文章---import Callout from '@/components/Callout.astro';import StepCard from '@/components/StepCard.astro';<Callout type="tip">这是一条提示信息。</Callout><StepCard step="1" title="第一步">操作说明...</StepCard>