掌握 Markdown：从基础语法到 GitHub 博文轻松发布

在数字化写作日益普及的今天，掌握一种简洁高效的标记语言变得越来越重要。Markdown 因其轻量、易读易写的特性，受到了广大写作者和开发者的青睐。同时，GitHub 作为全球最大的代码托管平台，也为我们提供了便捷的博客发布功能。本文将带你全面了解 Markdown 的常用语法，并详细介绍如何将你的 Markdown 博文上传到 GitHub。

第一部分：Markdown 格式写作要求与举例

Markdown 的目标是实现「易读易写」。一份使用 Markdown 格式撰写的文件应该可以直接以纯文本发布，并且看起来不会像是由许多标签或是格式指令所构成。

以下是一些常用的 Markdown 语法：

1. 标题 (Headers)

在文字前加上 # 号，可以创建标题。# 的数量决定了标题的级别，最多支持六级标题。

示例：

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

2. 段落 (Paragraphs)

段落是最基本的文本单元。段落之间通过一个或多个空行来分隔。

示例：

1
2
3

这是一个段落。

这是另一个段落。

3. 强调 (Emphasis)

加粗 (Bold)：使用两个 ** 或 __ 包裹文字。
斜体 (Italic)：使用一个 * 或 _ 包裹文字。
加粗并斜体 (Bold and Italic)：使用三个 *** 或 ___ 包裹文字。

示例：

**这是加粗的文字**
__这也是加粗的文字__

*这是斜体的文字*
_这也是斜体的文字_

***这是加粗并斜体的文字***
___这也是加粗并斜体的文字___

4. 列表 (Lists)

无序列表 (Unordered Lists)：使用 *、+ 或 - 作为列表标记。
有序列表 (Ordered Lists)：使用数字加英文句点 . 作为列表标记。

示例：

* 项目一
* 项目二
* 项目三

- 项目 A
- 项目 B
- 项目 C

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

5. 链接 (Links)

行内式链接：[链接文字](链接地址)
参考式链接：在文末定义链接，然后在需要的地方引用。

示例（行内式）：

1 2	`[访问我的博客](https://example.com) [访问我的博客并带有标题](https://example.com "博客标题")`

6. 图片 (Images)

与链接类似，只是在前面多一个 !。
行内式图片：![图片替代文字](图片链接)

示例：

1	`![谷歌 Logo](https://www.google.com/images/branding/googlelogo/2x/googlelogo_color_272x92dp.png)`

7. 代码 (Code)

行内代码 (Inline Code)：使用反引号 ` 包裹代码。
代码块 (Code Blocks)：使用三个反引号 ``` 包裹代码块，并可以指定语言类型。

示例：

这是一个行内代码的例子：`print("Hello, World!")`。

这是一个 Python 代码块：
```python
def greet(name):
    print(f"Hello, {name}!")

这是一个 JavaScript 代码块：

1	`console.log("Hello, World!");`


### 8. 引用 (Blockquotes)

在段落前加上 `>` 符号。

* 示例：
    ```markdown
    > 这是一段引用的文字。
    >
    > > 嵌套引用也是可以的。

9. 分隔线 (Horizontal Rules)

使用三个或以上的 *、- 或 _ 来创建分隔线，行内不能有其他字符。

示例：
1
2
3
*** --- ___

10. 表格 (Tables) (通常是 Markdown 扩展语法，GitHub 支持)

使用 | 分隔单元格，使用 - 分隔表头和表内容，并可以使用 : 控制对齐方式。

示例：

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

第二部分：GitHub 博文上传流程

将 Markdown 博文上传到 GitHub 并通过 GitHub Pages 展示，通常有以下几种方式：

方式一：直接在 GitHub 仓库中创建/上传文件

这是最简单直接的方式，适合初学者。

创建/选择仓库 (Repository)：
- 新建仓库： 如果你还没有用于存放博客的仓库，可以新建一个。通常命名为 <username>.github.io（其中 <username> 是你的 GitHub 用户名），这样可以直接通过 https://<username>.github.io 访问。
- 已有仓库： 如果你已经有仓库，可以直接使用。你可能需要在仓库的 Settings -> Pages 中配置 GitHub Pages 的源。
创建/上传 Markdown 文件：
- 创建新文件： 在你的仓库中，点击 “Add file” -> “Create new file”。
- 命名文件： 给你的博文文件命名，通常以 .md 或 .markdown 作为后缀，例如 my-first-post.md。你也可以创建文件夹来组织博文，例如 _posts/YYYY-MM-DD-your-post-title.md (Jekyll 格式，GitHub Pages 常用的静态站点生成器)。
- 撰写内容： 在编辑器中粘贴或撰写你的 Markdown 内容。
- 上传文件： 如果你已经在本地写好了 Markdown 文件，可以选择 “Add file” -> “Upload files”，然后将文件拖拽或选择上传。
提交更改 (Commit changes)：
- 在页面下方，你会看到 “Commit new file” 或 “Commit changes” 的区域。
- 填写提交信息 (Commit message)，简要描述你这次的更改，例如 “Add my first blog post”。
- 选择提交到主分支 (通常是 main 或 master) 或创建一个新的分支进行提交 (推荐用于协作或复杂更改)。
- 点击 “Commit new file” 或 “Commit changes”。
查看博文 (如果使用 GitHub Pages)：
- 如果你使用的是 <username>.github.io 仓库，或者在其他仓库中正确配置了 GitHub Pages，稍等片刻 (GitHub Pages 需要一些时间来构建和部署)，你就可以通过相应的 URL 访问你的博文了。
- 例如：https://<username>.github.io/my-first-post.html (如果直接放在根目录) 或 https://<username>.github.io/_posts/your-post-title.html (如果使用 Jekyll 结构，链接格式可能因配置而异)。

方式二：使用 Git 进行本地管理和推送

这种方式更专业，也更灵活，适合熟悉 Git 操作的用户。

安装 Git： 如果你本地还没有安装 Git，请先下载并安装。

克隆仓库 (Clone Repository)：

打开你的终端或 Git Bash。

将你的 GitHub 仓库克隆到本地：

1	`git clone [https://github.com/](https://github.com/)<username>/<repository-name>.git`

例如：

1	`git clone [https://github.com/yourusername/yourusername.github.io.git](https://github.com/yourusername/yourusername.github.io.git)`

创建/编辑 Markdown 文件：
- 在本地克隆下来的仓库文件夹中，创建或修改你的 Markdown 博文文件。你可以使用任何你喜欢的文本编辑器 (如 VS Code, Sublime Text, Typora 等)。

添加、提交和推送更改：

打开终端或 Git Bash，进入你的本地仓库目录。

添加文件到暂存区：

1
2
3

git add your-post-file.md  # 添加指定文件
# 或者
git add .  # 添加所有更改的文件

提交更改到本地仓库：

1	`git commit -m "Added new blog post: Your Post Title"`

推送到 GitHub 远程仓库：

1	`git push origin main # 或者你的主分支名称，如 master`

查看博文 (如果使用 GitHub Pages)：
- 同样，稍等片刻让 GitHub Pages 构建和部署，然后通过 URL 访问。

方式三：使用静态站点生成器 (如 Jekyll, Hugo, Hexo 等)

这是更高级的方式，可以让你构建功能更丰富的博客，但学习曲线也相对陡峭一些。

选择并安装静态站点生成器： 例如 Jekyll (Ruby), Hugo (Go), Hexo (Node.js)。
初始化项目： 根据所选生成器的文档初始化你的博客项目。
创建 Markdown 博文： 通常在特定的目录 (如 _posts) 下创建 Markdown 文件。这些生成器通常有自己的文件命名和 Front Matter (文件头部元数据) 规范。
本地预览： 大多数生成器都支持本地服务器，方便你实时预览效果。
生成静态文件： 运行生成命令 (如 jekyll build, hugo, hexo generate)，将 Markdown 文件等转换为 HTML、CSS 和 JavaScript 文件。
部署到 GitHub Pages：
- 方法一：手动推送 docs 目录或 gh-pages 分支： 将生成器生成的静态文件目录 (通常是 _site, public, docs 等) 中的内容推送到你的 GitHub 仓库的 main 分支的 /docs 文件夹，或者一个名为 gh-pages 的分支，并在 GitHub Pages 设置中选择对应的源。
- 方法二：使用 GitHub Actions 自动化部署： 这是推荐的方式，可以配置 GitHub Actions 在你推送到特定分支 (如 main) 时，自动运行构建命令并部署到 gh-pages 分支或发布到 GitHub Pages。

一些 GitHub Pages 的小提示：

默认主题： GitHub Pages 允许你选择一些预设的主题，可以在仓库的 Settings -> Pages 中进行配置。
自定义域名： 你可以将自己的域名指向你的 GitHub Pages 博客。
Jekyll： GitHub Pages 对 Jekyll 有原生支持。如果你将 Markdown 文件按照 Jekyll 的规范组织 (例如在 _posts 目录下，文件名格式为 YYYY-MM-DD-title.md)，GitHub Pages 会自动为你构建网站。

结语：

Markdown 以其简洁高效的特性，让内容创作回归本质。而 GitHub 则为我们提供了强大的平台来分享和展示我们的作品。希望通过本文的介绍，你能熟练掌握 Markdown 的基本语法，并顺利地在 GitHub 上发布你的博文。开始你的创作之旅吧！

使用建议：

实际操作： 最好在阅读时，自己动手尝试这些 Markdown 语法和 GitHub 上传流程。
截图辅助： 在你的博文中，可以加入 GitHub 操作界面的截图，使流程更清晰易懂。
个性化： 根据你的目标读者和个人风格，调整博文的语气和深度。
举一反三： Markdown 的语法还有更多高级用法 (如任务列表、脚注、定义列表等)，可以鼓励读者进一步探索。

我的GitHub仓库

第三部分、我的博客的文章建立与上传

创建一个新post

1	`$ hexo new "My New Post"`

More info: Writing

Run server

1	`$ hexo server`

More info: Server

Generate static files

1	`$ hexo generate`

More info: Generating

Deploy to remote sites

1	`$ hexo deploy`

More info: Deployment

写作

#原创

掌握 Markdown：从基础语法到 GitHub 博文轻松发布

https://xingdayup.github.io/2025/05/07/blog_post/

Author

Jesse Chen

Posted on

May 7, 2025

Licensed under

UKB数据提取 Previous

《小苏加油》 Next