Markdown 模板

Markdown 模板是什么

用 Markdown 写东西的时候，你有没有遇到过这种情况——每次新建文件都要从头搭建结构，标题层级、目录格式、代码块风格……反复敲一遍。

Markdown 模板就是解决这个问题的。它是一套预先定义好结构的 Markdown 文件框架，你可以直接复制过来，填上自己的内容就走人。不管是写项目 README、技术文档、会议记录还是周报，都有对应的模板可以直接用。

说实话，我自己用了好几年 Markdown，真正体会到模板的威力是在维护一个多人文档仓库的时候。当时团队里每个人写的文档格式都不一样——有人用三级标题开头，有人上来就放表格。后来统一用了一套文档模板，整个仓库的阅读体验立刻就上了一个档次。

常用 Markdown 模板大全

下面这些模板我都实际用过或者见过不错的设计，每种模板都给出了完整代码，直接复制就能用。

README 模板

GitHub 项目的门面，一个好的 README markdown template 能让访客 30 秒内搞清楚你的项目是干什么的。


> 一句话描述你的项目做什么

## 功能特性

- 特性一：简要说明
- 特性二：简要说明
- 特性三：简要说明

## 快速开始

### 安装

```bash
npm install your-package

使用

import { something } from 'your-package'

something.init()

配置说明

参数	类型	默认值	说明
option1	string	'default'	参数说明
option2	number	100	参数说明

常见问题

Q: 遇到 XX 问题怎么办？

A: 检查你的配置文件是否正确。

贡献指南

Fork 本仓库
创建特性分支 (git checkout -b feature/amazing-feature)
提交改动 (git commit -m 'Add some amazing feature')
推送到分支 (git push origin feature/amazing-feature)
提交 Pull Request

许可证

MIT License


### 技术文档模板

写技术文档最怕的就是结构混乱，读者翻半天找不到想看的内容。下面这个模板参考了社区里比较成熟的技术文档结构，适合 API 文档、系统设计文档等场景。

```markdown
# 文档标题

## 概述

简要描述本文档的目的、适用范围和目标读者。

## 目录

- [背景](#背景)
- [设计方案](#设计方案)
- [使用方法](#使用方法)
- [示例](#示例)
- [常见问题](#常见问题)

## 背景

描述问题背景、需求和现有方案的不足。

## 设计方案

### 整体架构

描述系统的整体架构和核心组件。

### 技术选型

| 方案 | 优点 | 缺点 |
|------|------|------|
| 方案 A | 简单直接 | 扩展性差 |
| 方案 B | 性能好 | 实现复杂 |

## 使用方法

### 前置条件

- Node.js >= 18
- npm >= 9

### 安装步骤

1. 克隆仓库
2. 安装依赖
3. 启动服务

## 示例

```bash
# 启动开发服务器
npm run dev

常见问题

问题 1

症状：XXX 不工作

原因：XXX 配置有误

解决：修改 XXX 配置项

更新日志

日期	版本	变更内容
2025-01-15	v1.0.0	初始版本


### 变更日志（Changelog）模板

[Keep a Changelog](https://keepachangelog.com) 是社区公认的变更日志标准格式。我之前在团队项目里推行这个格式，最大的感受是——它让 changelog 终于变得对人类友好了，不再是 git log 的复制粘贴。

```markdown
# Changelog

本文件记录项目所有重要变更。

格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/)，
版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。

## [Unreleased]

### Added
- 新增 XXX 功能

### Changed
- 修改了 XXX 的行为

### Fixed
- 修复了 XXX 问题

## [1.0.0] - 2025-01-15

### Added
- 初始发布版本
- 支持基本的 XXX 功能
- 完整的 API 文档

会议记录模板

这个模板我用了大概两年，几经调整才变成现在这个样子。关键是信息密度要够——开会不是聊天，每条讨论项都要有结论或后续动作。

# 会议记录：{会议主题}

- **日期**：YYYY-MM-DD
- **参会人**：张三、李四、王五
- **记录人**：张三

## 议题一：{议题名称}

**背景**：为什么要讨论这个

**讨论要点**：
- 要点 1
- 要点 2

**结论**：XXX

**后续行动**：

| 负责人 | 任务 | 截止日期 |
|--------|------|----------|
| 张三 | 完成 A 任务 | 01-20 |
| 李四 | 完成 B 任务 | 01-25 |

## 议题二：{议题名称}

**背景**：简要说明

**讨论要点**：
- 要点 1

**结论**：XXX

**后续行动**：
- 张三：跟进 XX 事项

## 下次会议

- 时间：YYYY-MM-DD
- 预计议题：XXX

周报/工作汇报模板

# 周报 — {姓名} — 第 {N} 周

## 本周完成

- [x] 任务 A：完成了 XXX
- [x] 任务 B：完成了 XXX
- [ ] 任务 C：进行中（进度 70%）

## 遇到的问题

1. **问题描述**：XXX
   - 影响范围：XXX
   - 当前状态：已解决 / 跟进中

## 下周计划

- [ ] 任务 D
- [ ] 任务 E

## 需要的支持

- 需要团队 B 配合 XXX

怎么创建自己的 Markdown 模板

上面那些现成模板可以直接用，但很多时候你需要根据自己的需求做调整，甚至从零创建。这里讲一下我的方法。

确定模板结构

创建模板之前，先想清楚三个问题：

谁会看这个文档 — 是给自己看的笔记，还是给团队看的文档，还是给外部用户看的说明
核心信息是什么 — 这个文档必须包含哪些内容，不能少
更新频率 — 是一次性的还是需要反复更新

比如写博客文章模板和写 API 文档模板，结构就完全不同。博客文章可能只需要标题、正文和标签，但 API 文档需要请求参数表、返回值说明、错误码列表。

用 Front Matter 添加元数据

如果你用 Hugo、Jekyll 这类静态站点生成器，或者 Obsidian 这类笔记工具，Front Matter 基本上是标配。它放在文件最开头，用 --- 包裹，用来定义文档的元信息：

---
title: 文章标题
date: 2025-01-15
tags: [markdown, tutorial]
author: 张三
draft: false
---

## 正文从这里开始

我之前从 Hexo 迁移到 Hugo 的时候，才发现两个平台对 Front Matter 的处理方式不一样——Hugo 默认用 TOML 格式（+++ 包裹），Jekyll 用 YAML 格式（--- 包裹）。后来我统一用 YAML，因为兼容性更好，大多数工具都认。

模板变量的使用

当模板里需要动态内容时，可以用变量占位符。不同工具用的语法不一样：

工具/引擎	变量语法	示例
GitHub Issues/PR	`{{变量名}}`	`{{title}}`
Jekyll/Liquid	`{{ page.title }}`	`{{ page.title }}`
Hugo	`{{ .Title }}`	`{{ .Title }}`
Handlebars/Mustache	`{{变量名}}`	`{{name}}`
Jinja2 (Python)	`{{ 变量名 }}`	`{{ title }}`

举个例子，GitHub 的 Issue 模板可以用 YAML Front Matter 定义表单字段，配合 Markdown 正文：

---
name: Bug 报告
about: 报告一个 bug
title: '[BUG] '
labels: bug
---

## Bug 描述

简要描述遇到的问题。

## 复现步骤

1. 进入 XXX 页面
2. 点击 XXX 按钮
3. 看到 XXX 错误

## 期望行为

应该出现什么

## 实际行为

实际出现了什么

## 环境

- 操作系统：
- 浏览器：
- 版本号：

保存和复用模板

模板建好之后，有几种常见的复用方式：

本地文件：把模板放在一个固定目录（比如 ~/templates/），需要的时候复制过来
GitHub：建一个 dotfiles 或 markdown-templates 仓库统一管理
编辑器片段（Snippet）：VS Code 支持用户自定义代码片段，可以把模板绑定到快捷键上
CLI 工具：用 cookiecutter 这类工具，一条命令从模板生成项目骨架

对了，VS Code 的 Snippet 功能可能很多人没用过。在 VS Code 里按 Ctrl+Shift+P，搜 "Configure User Snippets"，选 markdown.json，就可以定义自己的 Markdown 模板片段了。比如定义一个 readme 快捷命令，输入后自动展开成完整的 README 模板结构。

不同平台的 Markdown 模板

Markdown 本身是个很松散的规范，各平台的"方言"差别挺大。同一个模板在 GitHub 上好好的，搬到别的平台可能就出问题了。

GitHub 模板

GitHub 是 Markdown 模板用得最多的地方。除了 README 模板，GitHub 还支持：

Issue 模板：放在 .github/ISSUE_TEMPLATE/ 目录下
PR 模板：放在 .github/PULL_REQUEST_TEMPLATE.md
讨论模板：放在 .github/DISCUSSION_TEMPLATE/ 目录下

GitHub 用的是 GitHub Flavored Markdown（GFM），在标准 Markdown 基础上扩展了表格、任务列表、删除线、自动链接等功能。

Obsidian 笔记模板

Obsidian 的核心插件里有专门的"模板"功能。你可以在设置里指定一个模板文件夹，然后通过快捷键或命令面板插入模板内容。

Obsidian 模板支持日期变量，比如 {{date}} 和 {{time}}，还可以配合 Templater 社区插件实现更强大的动态模板。

VS Code 中的模板

除了前面说的 Snippet，VS Code 还有一些扩展专门做 Markdown 模板管理，比如 "Markdown All in One" 就提供了快捷操作。如果你经常写 Markdown，这个扩展基本上是必装的。

常见问题

Markdown 模板和普通 Markdown 文件有什么区别？

本质上没有区别——模板就是一个普通的 Markdown 文件，只是它预留了占位符和结构骨架，方便你重复使用。你可以把任何写得不错的 Markdown 文档改造成模板，只需要把具体内容替换成通用描述或变量就行。

为什么我的模板在 GitHub 上显示正常，到其他平台就乱了？

因为各平台的 Markdown 解析器不一样。GitHub 用的是 GFM，支持表格、任务列表、脚注等扩展语法。但有些平台（比如一些邮件客户端）只支持基本 Markdown。写通用模板时，尽量用基础语法，少用平台特有的扩展。

怎么让团队统一使用模板？

最简单的办法是把它放到项目仓库里。比如在团队仓库的根目录放一个 docs/templates/ 文件夹，新人文档或 PR 模板从这里复制。再配合 CI 检查（比如用 markdownlint 检查格式），就能逐步统一。

参考来源

Basic Syntax - Markdown Guide — Markdown 基础语法权威参考
GitHub Docs - Writing on GitHub — GitHub Flavored Markdown 官方文档
Keep a Changelog — 变更日志格式的社区标准
CommonMark Spec — Markdown 标准规范
GitHub Markdown Templates — GitHub 上的 Markdown 模板合集