markdown文件写作

1. 推荐markdown编辑器

vuepress中的内容都是由markdown生成的，所以编写网页内容需要使用markdown进行写作。

推荐使用Typora为markdown的编辑器。下载地址 (opens new window)。

Typora的优点是可以直接在markdown生成的效果中编辑，而不是在源代码中，页面更加美观，效果也更加直观。

2. 图片展示

markdown中可以插入图片，但是图片不是存储在markdown文件中，而是通过访问路径打开的。

vuepress中如果想要使用本地路径，可以把图片放在docs/.vuepress/public目录下。可是当图片太多的时候，博客会非常臃肿，访问速度也会变慢。

建议搭建图床，通过在线访问的链接添加图片。

搭建图床的方式有很多种，比如阿里云OSS，腾讯云COS，七牛云等付费服务。

这里推荐使用 GitHub + PicGo + jsDelivr 搭建免费图床。搭建教程 (opens new window)

3. 构建博客目录并使用markdown编辑博客内容

在/docs文件夹中，除了.vuepress、@pages、_posts、index.md 或 README.md之外的文件夹将生成博客的内容，并自动为其生成对应的侧边栏。生成的顺序取自序号，标题取自文件（夹）名称。

3.1 命名约定

• 无论是文件还是文件夹，请为其名称添加上正确的正整数序号和.，从00或01开始累计，如01.文件夹、02.文件.md，vdoing将会按照序号的顺序来决定其在侧边栏当中的顺序。
• 同一级别目录内即使只有一个文件或文件夹也要为其加上序号。
• 文件或文件夹名称中间不能出现多余的点.，如01.我是.名称.md中间出现.将会导致解析错误。

提示

序号只是用于决定先后顺序，并不一定需要连着，如01、02、03...，实际工作中可能会在两个文章中间插入一篇新的文章，因此为了方便可以采用间隔序号10、20、30...，后面如果需要在10和20中间插入一篇新文章，可以给定序号15。

3.2 级别说明

源目录（一般是docs）底下的级别现在我们称之为一级目录，一级目录的下一级为二级目录，以此类推，最多到四级目录。

• 一级目录
  1. .vuepress、@pages、_posts、index.md 或 README.md 这些文件(文件夹)不参与数据生成。
  2. 序号非必须。（如一些专栏，可以不用序号)
• 二级目录
  1. 该级别下可以同时放文件夹和.md文件，但是两者序号要连贯（参考下面的例子中的其他）。
  2. 必须有序号
• 三级目录
  • (同上)
• 四级目录
  1. 该级别下只能放.md文件。
  2. 必须有序号

所有级别内至少有一个文件或文件夹。

3.3 目录结构的例子

.
├── docs
│   │  (不参与数据生成)
│   ├── .vuepress
│   ├── @pages
│   ├── _posts
│   ├── index.md
│   ├── 01.Java
│   │   ├── 01.JavaSE
│   │   |   ├── 01.java基础语法.md
│   │   |   ├── 02.类型转换、运算符、流程控制语句.md
│   │   |   └── 03.switch&循环语句.md
│   │   └── 02.JavaWeb
│   │   |   ├── 01.MySql基础.md
│   │   |   └── 02.MySql约束.md
│   ├── 02.前端
│   │   ├── 01.Html
│   │   |   ├── 01.浏览器与渲染引擎.md
│   │   |   └── 02.认识网页标签.md

4. 自动生成front matter

在运行开发服务npm run dev或打包npm run build时将自动为还没生成front matter (opens new window) (opens new window)的markdown文件自动生成front matter。

front matter的内容包括：

• 标题(title)
• 时间(date)
• 永久链接(permalink)
• 分类(categories)
• 标签(tags)时

例如：

title: 初识Java：Java帝国的诞生
date: 2021-10-19 09:02:11
permalink: /pages/899940/
categories:
  - Java
  - JavaSE
tags:
  - 

你也可以自己手动设置或者修改这些数据。当你手动设置之后，相应的数据就不会再自动生成。

5. 写文章时的流程

写文章时，大概的流程是这样的：

1.创建.md文件，如果在结构化目录下则需要添加相应的序号，在碎片化博文目录_posts下不需要添加序号，文件名填写文章的标题。

2.如果你想手动指定文章的分类、标签，则需要在头部front matter填写相应的字段。一般情况下不需要再填写其他字段。不想手动指定分类和标签也可以省略这一步。

---
categories: 
  - 分类1
tags: 
  - 标签1
  - 标签2
---

3.关于一级标题，即markdown中的一级标题(# 标题)，你可以写也可以不写，在页面中实际显示的文章标题是取自front matter中的title，然后把.md中的一级标题隐藏了。

这样做既可以保留本地文件的一级标题，也可以兼容线上页面的标题。 同时，对于在新建.md文件时已经输入了一次标题在文件名，不想在文档中重复输入一次标题的，也是可以实现的。

4.关于文章摘要，你想在首先文章列表中显示摘要时可以在合适的位置添加一个<!-- more -->注释，参考：添加摘要 (opens new window)

5.然后就到你自由发挥的时间啦。