layout: post
title: markdown语法和一种markdown博客搭建方法
description: markdown是时下流行的轻量级的文本标记语言。即，用几种非常简单的符号来标记格式，让作者可以忽略排版，而专注于文章内容的创作。另外，markdown 很容易插入源代码、flow chart、公式等技术人员常用的功能。并且可以轻松转换成html、pdf、doc、ppt等格式。因此，markdown也成为技术人员写文档的首选工具。本文也介绍了用php+markdown搭建个人博客的一种方法
keywords: markdown的语法,用php+markdown搭建个人博客的一种方法
author: admin
date: 2022-12-27 15:49
category: 网络技术
tags: markdown
---
## 1. Markdown 是什么
`markdown` 是时下流行的轻量级的文本标记语言。即，用几种非常简单的符号来标记格式，比如，#表示大标题，##表示小标题，>表示引用，\[\]\(\)表示插入链接，\!\[\]\(\)表示插入图片等。让作者可以忽略排版，而专注于文章内容的创作。另外，`markdown` 很容易插入源代码、flow chart、公式等技术人员常用的功能。并且可以轻松转换成html、pdf、doc、ppt等格式。因此，markdown也成为技术人员写文档的首选工具。
**Markdown** 是一种轻量级 标记语言，它以纯文本形式( 易读、易写、易更改 )编写文档，并最终以HTML格式发布。
Markdown也可以理解为将以MARKDOWN语法编写的语言转换成HTML内容的工具。
## 2. 谁创造了它？
它由[Aaron Swartz](http://www.aaronsw.com/)和**John Gruber**共同设计，**Aaron Swartz**就是那位于去年（*2013年1月11日*）自杀,有着**开挂**一般人生经历的程序员。维基百科对他的[介绍](http://zh.wikipedia.org/wiki/%E4%BA%9A%E4%BC%A6%C2%B7%E6%96%AF%E6%B2%83%E8%8C%A8)是：软件工程师、作家、政治组织者、互联网活动家、维基百科人。
他有着足以让你跪拜的人生经历：
+ **14岁** 参与RSS 1.0规格标准的制订。
+ **2004** 年入读斯坦福，之后退学。
+ **2005** 年创建[Infogami](http://infogami.org/)，之后与[Reddit](http://www.reddit.com/)合并成为其合伙人。
+ **2010** 年创立求进会（Demand Progress），积极参与禁止网络盗版法案（SOPA）活动，最终该提案被撤回。
+ **2011** 年7月19日，因被控从MIT和JSTOR下载480万篇学术论文并以免费形式上传于网络被捕。
+ **2013** 年1月自杀身亡。
天才都有早逝的归途。
## 3. 为什么要使用它？
+ 它是易读（看起来舒服）、易写（语法简单）、易更改纯文本。处处体现着极简主义的影子。
+ 兼容HTML，可以转换为HTML格式发布。
+ 跨平台使用。
+ 越来越多的网站支持Markdown。
+ 更方便清晰地组织你的电子邮件。（Markdown-here, Airmail）
+ 摆脱Word（我不是认真的）。
## 4. 怎么使用？
如果不算扩展，Markdown的语法绝对简单到让你爱不释手。
Markdown语法主要分为如下几大部分：
标题，段落，区块引用，代码区块，强调，列表，分割线，链接，图片，反斜杠 `\`，符号'`'。
### 4.1 标题
两种形式：
1）使用`=`和`-`标记一级和二级标题。
> 一级标题
> `=========`
> 二级标题
> `---------`
效果：
> 一级标题
> =========
> 二级标题
> ---------
2）使用`#`，可表示1-6级标题。
> \# 一级标题
> \## 二级标题
> \### 三级标题
> \#### 四级标题
> \##### 五级标题
> \###### 六级标题
效果：
> # 一级标题
> ## 二级标题
> ### 三级标题
> #### 四级标题
> ##### 五级标题
> ###### 六级标题
### 4.2 段落
段落的前后要有空行，所谓的空行是指没有文字内容。若想在段内强制换行的方式是使用两个以上空格加上回车（引用中换行省略回车）。
### 4.3 区块引用
在段落的每行或者只在第一行使用符号`>`,还可使用多个嵌套引用，如：
> \> 区块引用
> \>> 嵌套引用
效果：
> 区块引用
>> 嵌套引用
### 4.4 代码区块
代码区块的建立是在每行加上4个空格或者一个制表符（如同写代码一样）。如
普通段落：
void main()
{
printf("Hello, Markdown.");
}
代码区块：
void main()
{
printf("Hello, Markdown.");
}
注意:需要和普通段落之间存在空行。
### 4.5 强调
在强调内容两侧分别加上`*`或者`_`，如：
> \*斜体\*，\_斜体\_
> \*\*粗体\*\*，\_\_粗体\_\_
效果：
> *斜体*，_斜体_
> 粗体，__粗体__
### 4.6 列表
使用`·`、`+`、或`-`标记无序列表，如：
> \-（+\*） 第一项
> \-（+\*） 第二项
> \- （+\*）第三项
注意：标记后面最少有一个_空格_或_制表符_。若不在引用区块中，必须和前方段落之间存在空行。
效果：
> + 第一项
> + 第二项
> + 第三项
有序列表的标记方式是将上述的符号换成数字,并辅以`.`，如：
> 1 . 第一项
> 2 . 第二项
> 3 . 第三项
效果：
> 1. 第一项
> 2. 第二项
> 3. 第三项
### 4.7 分割线
分割线最常使用就是三个或以上`*`，还可以使用`-`和`_`。
### 4.8 链接
链接可以由两种形式生成：行内式和参考式。
行内式：
> \[嗨网\]\(https://higrid.net "Markdown"\)。
效果：
> [嗨网](https://higrid.net "Markdown")。
参考式：
> \[嗨网1\]\[1\]
> \[嗨网2\]\[2\]
> \[1\]:https://higrid.net "Markdown"
> \[2\]:https://higrid.net "Markdown"
效果：
> [嗨网1][1]
> [嗨网2][2]
[1]: https://higrid.net "Markdown"
[2]: https://higrid.net "Markdown"
注意：上述的`[1]:https://higrid.net "Markdown"`不出现在区块中。
### 4.9 图片
添加图片的形式和链接相似，只需在链接的基础上前方加一个`！`。
#### 4.10 反斜杠`\`
相当于反转义作用。使符号成为普通符号。
#### 4.11 符号'`'
起到标记作用。如：
>\`ctrl+a\`
效果：
>`ctrl+a`
### 5. *谁*在用？
Markdown的使用者：
+ GitHub
+ 简书
+ Stack Overflow
+ Apollo
+ Moodle
+ 等等
### 6. 尝试一下
+ Chrome下的插件诸如`stackedit`与`markdown-here`等非常方便，也不用担心平台受限。
+ 在线的dillinger.io评价也不错
+ Windowns下的MarkdownPad也用过，不过免费版的体验不是很好。
+ Mac下的Mou是国人贡献的，口碑很好。
+ Linux下的ReText不错。
当然，最终境界永远都是笔下是语法，心中格式化 :)。
注意：不同的Markdown解释器或工具对相应语法（扩展语法）的解释效果不尽相同，具体可参见工具的使用说明。
虽然有人想出面搞一个所谓的标准化的Markdown，[没想到还惹怒了健在的创始人John Gruber]
(http://blog.codinghorror.com/standard-markdown-is-now-common-markdown/ )。
以上基本是所有traditonal markdown的语法。
## 为什么要搭建文章分享博客
就个人来讲，可以
- 方便地记录工作笔记，好记性不如烂笔头。
- 只学习别人的经验，而不分享，似乎不厚道。来而不往非礼也。
- 利用博客与同行交流，可以纠正一些错误的认知，扩大朋友圈。
就公司来讲，可以
- 建立团队的知识库。
- 写项目总结，或者技术论文。
- 方便同事查阅曾经踩过坑，避免同一个坑里掉两次。
## 常用的建站后台语言和框架
- php（ThinkPHP）-> wordpress
- nodejs（express）-> Hexo
- python（Flask、Django）-> Django
- ruby（ruby on rails）-> JekyII
这些语言和框架都支持 `markdown` ，都可以作为个人博客来使用。主要看自己偏好哪种语言，或者哪个界面更酷。
## 简单的解析markdown采用的方案
本博客没有采用上面这些复杂的框架，而是采用原生php和开源的markdown parser自己搭建。更轻量，更灵活。
###### 目录结构
目录结构
index.php是系统的主程序，md是存放markdown源文件的目录。
###### php代码工作流程
首先，php输出必要的html文件头。
```html
```
然后，读取markdown文件，并提取文章标题，作为html的title输出。
index.php接收外部传递的参数，最简单的方法就是传入markdown的文件名。而由于后缀名相同，都是.md，所以省略后缀名，在php代码里再拼接回来。
```php
# url: index.php?md=web-01
$filename = "md/index.md";
if(isset($_GET['md']) && $_GET['md'] != ""){
$filename = "md/" . $_GET['md'] . ".md";
}
```
如果没有提供参数，就认为是index.md，即文章的目录。
然后，根据markdown文件名，读取markdown文件到php内部字符串。后续的所有操作都是针对这个字符串。
```php
$fh = fopen($filename, "r");
$contents = fread($fh, filesize($filename));
fclose($file);
```
接下来，从markdown字符串中提取文章的大标题。在markdown语法中，大标题是以单个#开头的行，所以我们用正则来提取。
```php
#extract title from markdown
if(preg_match('/\x{23}\x{20}(.*)/u', $contents, $matches)){
$title = ": " . $matches[1];
}else{
$title = "";
}
echo " \n";
echo "
```
调用markdown的parser， [parsedown](https://parsedown.org) ，把markdown转成html，方法如下：
```php
include "../parsedown/Parsedown.php";
$Parsedown = new Parsedown();
echo $Parsedown->text($contents);
```
给markdown转换的html增加格式，比如h1设置大号字体、居中，h2设置加框的小标题。这一部分属于css的范畴，不详细描述，下面给出一段简单的示例：
```css
.md {
font-family: "Microsoft Yahei";
word-break: break-all;
word-wrap: break-word;
}
.md h1 {
text-align: center;
font-size: 2em;
padding: 0.5em 0em 1em 0em;
}
.md h2 {
text-align: center;
font-size: 1.6em;
border: 1px dashed black;
padding: 0.5em;
margin-top: 3em;
margin-bottom: 1em;
}
.md blockquote {
border-left: 0.2em solid #008000;
margin-left: 0.5em;
padding: 0.5em;
}
.md img {
max-width:100%;
height: auto;
}
```
还有一个重要的部分是为markdown内部的源码加上高亮显示。开源的[highlight.js](https://highlightjs.org) ，是javascript脚本，可直接用于网页前端。如下：
```html
```
highlight.js支持160多种编程语言，当然对ICer的常用编程语言也支持，如verilog、sv、VHDL、Perl、Python、Tcl、Tk等。只需要在官网下载时，勾上自己喜欢的语言就好了。
## 手机的自适应方案
可以采用[bootstrap4](https://getbootstrap.com) ，bootstrap是一个css和javascript库，定义了常用的排版格式。这些格式可以根据屏幕尺寸和分辨率的大小自动调节。基本使用方法如下：
首先，包含bootstrap库文件。
```html
```
再在需要的地方加上bootstrap的css class，比如块文本两侧留白、居中显示。
```html
```
图片大小自适应：
```html
```
## 总结
本文介绍了一种php+markdown的博客搭建方法，不管对于个人建站，还是对于公司研发部门或项目团队建立知识分享平台，都很有意义。