Skip to main content

BJUT-SWIFT 发文指南

这篇教程将指导你如何在教程栏目中创建和编写一篇规范的文章。

––– views

介绍

在这篇教程中，我将介绍如何在 BJUT-SWIFT 官网中创建和编写一篇规范的文章。我们将学习文章的基本结构、格式要求以及一些实用的写作技巧。

环境配置

推荐使用：

  • VSCode 或者 Cursor 编辑器

务必使用：

  • AutoCorrect 插件 检查书写规范，防止出现丑陋的中英混写；
  • Bun 作为包管理器（而非 pnpm 或者 npm）

请参考 Bun 官网手册 下载 Bun 运行时，并配置环境变量。

然后运行 bun install 安装项目依赖，使用 bun run dev 启动项目，贡献前请务必保证你本地部署的网站可以正常工作。

修改完成后务必运行 bun lint:fix 检查代码格式，否则 GitHub CI 会报错。

文章结构

每篇教程文章都需要包含以下基本结构：

1. Frontmatter

Frontmatter 是文章最上方的元数据部分，即文章的基本信息，使用 --- 包裹，包含以下字段：

---
title: '文章标题'
tags: 'tag1,tag2'
description: '文章的简短描述'
---
 
> 注意：tags 之间使用英文逗号分隔，不要加空格

这些元数据会在文章顶部生成标题、标签和描述信息：

文章标题

标签：tag1, tag2

文章的简短描述

注意：tags 之间使用英文逗号分隔，不要加空格

2. 文章内容

文章主体应该包含以下部分：

  • 介绍: 简要说明本文要讲什么
  • 主要内容: 分步骤或主题展开
  • 总结: 总结关键点

3. 格式指南

Markdown 语法

文章使用 MDX 格式（Markdown 的扩展），支持以下常用语法：

详细的语法可以参考Markdown 语法指南

# 一级标题
 
## 二级标题
 
### 三级标题
 
- 无序列表
- 列表项
 
1. 有序列表
2. 列表项
 
**粗体文本**
_斜体文本_
 
[链接文本](URL)
 
> 引用文本
> 可以包含多行
>
> 空行开始新段落
>
> > 嵌套引用
 
表格：
| 表头 1 | 表头 2 |
|-------|-------|
| 单元格 | 单元格 |
| 左对齐 | 居中 |
 
任务列表：
 
- [x] 已完成任务
- [ ] 未完成任务

一级标题

二级标题

三级标题（n 个 # 即 n 级标题）

  • 无序列表
  • 列表项
  1. 有序列表
  2. 列表项

粗体文本 斜体文本

链接文本

引用文本 可以包含多行

空行开始新段落

嵌套引用

表格：

表头 1表头 2
单元格单元格
左对齐居中

任务列表：

  • 已完成任务
  • 未完成任务

代码块

对于代码示例，使用三个反引号包裹，并指定语言以获得语法高亮：

```python
# Python 代码示例
def hello_world():
    print("Hello, World!")
```
 
```javascript /sayHello/
// 通过 /text/ 来高亮一段代码
// JavaScript 代码示例
function sayHello() {
  console.log('Hello!');
}
```
 
```css {4}
/* 通过 {n} 来高亮第 n 行代码 */
/* CSS 代码示例 */
.button {
  color: blue;
}
```

支持多种编程语言的语法高亮：

# Python 代码示例
def hello_world():
    print("Hello, World!")
// 通过 /text/ 来高亮一段代码
// JavaScript 代码示例
function sayHello() {
  console.log('Hello!');
}
/* 通过 {n} 高亮第 n 行代码 */
/* CSS 代码示例 */
.button {
  color: blue;
}

图片插入

使用 github assets + cdn.bjutswift.cn 插入图片：

将 GitHub 上存储的图片 如图

通过cdn.bjutswift.cn这个 CDN 来加速该图片的访问 并获得该图片的 url

// 基本用法
<NextImage
  src="https://cdn.bjutswift.cn/https://raw.githubusercontent.com/bjut-swift/BJUT-Helper/refs/heads/master/images/title.png"
  alt="示例图片"
  width={800}
  height={500}
  useSkeleton
  className="w-full rounded-lg shadow-lg my-4"
/>
示例图片

并排插入两张图片

使用 Tailwind CSS 的 grid 布局可以轻松实现图片并排显示：

<div className='grid grid-cols-2 gap-4'>
  <NextImage alt='左侧示例图片' />
  <NextImage alt='右侧示例图片' />
</div>
左侧示例图片
右侧示例图片

关键类名说明：

  • grid: 使用网格布局
  • grid-cols-2: 将容器分为两列
  • gap-4: 设置列间距为 1rem

总结

创建一篇好的教程文章需要注意以下几点：

  • 遵循基本的文章结构
  • 使用正确的 Markdown 语法
  • 提供清晰的示例和说明
  • 保持格式规范统一
  • 注意内容的组织和展示
  • 关注读者的阅读体验

现在你已经了解了如何写一篇规范的教程文章，开始创作你的第一篇教程吧！

提示：第一次写作时可以参考这篇指南，熟悉后就能得心应手了。

项目相关

Metadata

  • 项目元数据文档

下面介绍多个项目的元数据，包括链接、视频的插入。元数据的结构设计使其易于集成到文档或项目管理工具中。

---
横幅图片: 'projects/hexcape/hexcape-banner_xdulxw'
链接: 'https://hexcape.thcl.dev'
YouTube视频: 'https://www.youtube.com/watch?v=oxaDSU1uNPc'
---

下面是一些例子

---
title: 'Hexcape'
description: 'A game that combines iOS and physical puzzle game, using 3D, 360 world view, and AR'
category: 'Team of 6'
publishedAt: '2022-12-21'
techs: 'swift'
banner: 'projects/hexcape/hexcape-banner_xdulxw'
link: 'https://hexcape.thcl.dev'
youtube: 'https://www.youtube.com/watch?v=oxaDSU1uNPc'
---
示例图片
---
title: 'Notiolink'
description: 'Self-hostable branded link shortener built with Next.js & Notion API'
category: 'Personal Project'
publishedAt: '2022-07-23'
techs: 'nextjs,tailwindcss,notion'
banner: 'projects/notiolink/notiolink_bjtkm5.png'
github: 'https://github.com/theodorusclarence/notiolink'
link: 'https://notiolink.thcl.dev'
---
示例图片
`<blockquote className='with-icons'>
  ## clarence.link
  <div className='not-prose mt-2'>
    <TechIcons techs={['nextjs', 'notion']} />
  </div>
</blockquote>`

Tech Stack Used

小组件

  • GithubCard
示例图片

这个组件的主要作用是获取并显示一个 GitHub 仓库的信息。当组件渲染时，它会自动发起请求获取数据，并将结果存储在 repository 变量中，同时处理可能出现的错误。

用法

> ## Try it out!
 
Deploy one of your own!
 
<GithubCard repo='theodorusclarence/notiolink' />
  • TechIcons

插入图标（icon）

用法

<blockquote className='with-icons'>
  ## Tech Stack Used
  <div className='not-prose mt-2'>
    <TechIcons techs={['nextjs', 'tailwindcss', 'notion']} />
  </div>
</blockquote>

Tech Stack Used

  • LiteYouTubeEmbed
示例图片

源代码如下

<LiteYouTubeEmbed
  id='oxaDSU1uNPc'
  poster='maxresdefault'
  title='Hexcape Features'
  noCookie={true}
/>
示例图片

源代码如下

> ## Demo Video
 
<LiteYouTubeEmbed
  id='NZf-xuB-Lxg'
  poster='maxresdefault'
  title='Voting Page Demo'
  noCookie={true}
/>

总结下来的用法：

  <h2>Hexcape Features</h2>
      <LiteYouTubeEmbed
        id='oxaDSU1uNPc'       // YouTube 视频的 ID
        poster='maxresdefault' // 视频的封面图，可以使用 'maxresdefault' 作为默认值
        title='Hexcape Features' // 视频的标题
        noCookie={true}        // 使用 YouTube 的 no-cookie 模式
      />
    </div>

最后检查

  1. 重要的事情说三遍：
  • 贡献前保证你在本地运行能正常渲染，没有报错，修改完成后务必运行 bun lint:fix 检查代码格式！否则 GitHub CI 会报错。
  • 贡献前保证你在本地运行能正常渲染，没有报错，修改完成后务必运行 bun lint:fix 检查代码格式！否则 GitHub CI 会报错。
  • 贡献前保证你在本地运行能正常渲染，没有报错，修改完成后务必运行 bun lint:fix 检查代码格式！否则 GitHub CI 会报错。

  1. 确保你按照 AutoCorrect 插件的提示修改了书写规范

  2. 提交时要注意 Commit Lint 的规范，参考 commitlint.config.js 文件，诸如 update readme 这样的不规范提交是无法通过自动检查的。

Edit this on GitHub← Back to shorts