markdown语法和一种markdown博客搭建方法
1. Markdown 是什么
markdown
是时下流行的轻量级的文本标记语言。即,用几种非常简单的符号来标记格式,比如,#表示大标题,##表示小标题,>表示引用,[]()表示插入链接,![]()表示插入图片等。让作者可以忽略排版,而专注于文章内容的创作。另外,markdown
很容易插入源代码、flow chart、公式等技术人员常用的功能。并且可以轻松转换成html、pdf、doc、ppt等格式。因此,markdown也成为技术人员写文档的首选工具。
Markdown 是一种轻量级 标记语言,它以纯文本形式( 易读、易写、易更改 )编写文档,并最终以HTML格式发布。
Markdown也可以理解为将以MARKDOWN语法编写的语言转换成HTML内容的工具。
2. 谁创造了它?
它由Aaron Swartz和John Gruber共同设计,Aaron Swartz就是那位于去年(2013年1月11日)自杀,有着开挂一般人生经历的程序员。维基百科对他的介绍是:软件工程师、作家、政治组织者、互联网活动家、维基百科人。
他有着足以让你跪拜的人生经历:
- 14岁 参与RSS 1.0规格标准的制订。
- 2004 年入读斯坦福,之后退学。
- 2005 年创建Infogami,之后与Reddit合并成为其合伙人。
- 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 . 第三项
效果:
- 第一项
- 第二项
- 第三项
4.7 分割线
分割线最常使用就是三个或以上*
,还可以使用-
和_
。
4.8 链接
链接可以由两种形式生成:行内式和参考式。
行内式:
[嗨网](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文件头。
<!DOCTYPE html>
<html>
<head>
<meta charset=utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0">
然后,读取markdown文件,并提取文章标题,作为html的title输出。
index.php接收外部传递的参数,最简单的方法就是传入markdown的文件名。而由于后缀名相同,都是.md,所以省略后缀名,在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内部字符串。后续的所有操作都是针对这个字符串。
$fh = fopen($filename, "r");
$contents = fread($fh, filesize($filename));
fclose($file);
接下来,从markdown字符串中提取文章的大标题。在markdown语法中,大标题是以单个#开头的行,所以我们用正则来提取。
#extract title from markdown
if(preg_match('/\x{23}\x{20}(.*)/u', $contents, $matches)){
$title = ": " . $matches[1];
}else{
$title = "";
}
echo " <meta name=\"description\" content=\"分享文章: $title\" />\n";
echo " <title>" . $title . "</title>\n";
调用markdown的parser, parsedown ,把markdown转成html,方法如下:
include "../parsedown/Parsedown.php";
$Parsedown = new Parsedown();
echo $Parsedown->text($contents);
给markdown转换的html增加格式,比如h1设置大号字体、居中,h2设置加框的小标题。这一部分属于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 ,是javascript脚本,可直接用于网页前端。如下:
<link rel="stylesheet" href="../highlight/styles/tomorrow-night.css">
<script src="../highlight/highlight.pack.js"></script>
<script>
hljs.initHighlightingOnLoad();
</script>
highlight.js支持160多种编程语言,当然对ICer的常用编程语言也支持,如verilog、sv、VHDL、Perl、Python、Tcl、Tk等。只需要在官网下载时,勾上自己喜欢的语言就好了。
手机的自适应方案
可以采用bootstrap4 ,bootstrap是一个css和javascript库,定义了常用的排版格式。这些格式可以根据屏幕尺寸和分辨率的大小自动调节。基本使用方法如下:
首先,包含bootstrap库文件。
<link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.1.3/css/bootstrap.min.css" crossorigin="anonymous">
<script src="https://code.jquery.com/jquery-3.3.1.slim.min.js" crossorigin="anonymous"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.14.3/umd/popper.min.js" crossorigin="anonymous"></script>
<script src="https://stackpath.bootstrapcdn.com/bootstrap/4.1.3/js/bootstrap.min.js" crossorigin="anonymous"></script>
再在需要的地方加上bootstrap的css class,比如块文本两侧留白、居中显示。
<div class="container"></div>
图片大小自适应:
<img class="img_fluid">
总结
本文介绍了一种php+markdown的博客搭建方法,不管对于个人建站,还是对于公司研发部门或项目团队建立知识分享平台,都很有意义。