用sublime来撰写markdown文档

• 用sublime来撰写markdown文档
  • 摘要
  • 什么是markdown
  • 安装Markdown Preview插件
  • 配置Markdown Preview插件
    • 配置快捷键
    • 代码高亮
    • 配置css文件
  • 几个常用的markdown语法示例
    • 标题
    • 列表
    • 弹出式注释
    • 定义列表
    • 代码片段
    • 角注
    • 表格
    • 警告
    • 强调
    • 超链接
    • 引用
    • 图片
    • 目录
  • 练习
  • 最佳实践

摘要

本文包含两部分内容：

1. 在sublime里安装Markdown Preview插件来实现markdown文件的预览
2. 介绍markdown常用的语法，让初次接触markdown的人可以在短时间内掌握常用的语法和句法

什么是markdown

Markdown 是一种轻量级标记语言，它允许人们使用易读易写的纯文本格式编写文档，然后转换成格式丰富的HTML页面。 —— 维基百科

安装Markdown Preview插件

推荐的安装方法是通过Package Control来安装：

1. 如果你的sublime还没有安装Package Control，需要先点击这里查看安装方法
2. 使用 ctrl + shift + P 来打开命令窗口，输入并选择 Package Control: Install Package
3. 在弹出的窗口里，输入 Markdown Preview并按回车来完成安装

配置Markdown Preview插件

配置快捷键

通过 Preferences -> Key Bindings - User打开sublime的快捷键配置文件，把下面内容复制到这个设置文件里保存。

{ "keys": ["alt+m"], "command": "markdown_preview", "args": {"target": "browser", "parser":"markdown"} }

配置完成后，按下alt + m即可直接在浏览器里预览markdown的写作效果。

代码高亮

markdown里嵌入的代码在生成html文档时，支持根据语言高亮显示。通过 Preferences -> Package Settings -> Markdown Preview -> Settings-User 来打开用户设置文件，加入如下内容即可打开代码高亮功能。

{    "enable_highlight": true}

如果需要更高级的高亮显示，比如指定代码高亮的风格(emacs, vim etc.)，则可以自定义 codehilite 扩展来实现。在Markdown Preview用户设置文件里加入如下内容即可。本文就是使用 emacs 高亮风格来显示代码的。

{    "enabled_extensions": [            "extra",             "github",             "toc",             "headerid",             "meta",             "sane_lists",             "smarty",             "wikilinks",            "admonition",            "codehilite(guess_lang=False,pygments_style=emacs)"        ]}

关于pygments

pygments_style可以用来指定代码高亮的风格。Markdown Preview使用pygments来完成代码高亮。关于pygments以及更多可用的内置代码高亮风格，可访问pygments官网查阅相关文档。

配置css文件

Markdown Preview生成的HTML文件，在浏览器里查看时其默认的宽度为45em，如果你觉得生成的网页太窄，可以修改一下css文件。
打开Markdown Preview的安装目录，找到markdown.css和github.css文件，查找下面的内容：

    body {      width: 45em;      border: 1px solid #ddd;      outline: 1300px solid #fff;      margin: 16px auto;    }

把里面的45em修改为80%或者你认为合适的尺寸即可。

sublime安装包目录与格式

• Linux环境
  通过 Package Control: List Packages ，在己安装的Packages里选择 Markdown Preview 会直接打开Markdown Preview的安装目录，在打开的目录中直接可以找到markdown.css和github.css。
• Windows环境
  在sublime安装目录下，找到 Data\Installed Packages 目录，这个目录就是安装包的目录。如果已经安装好Markdown Preview，可以看到文件 Markdown Preview.sublime-package 。这个其实是一个zip包。直接用系统里的压缩工具打开，然后在压缩包的根目录下查找markdown.css和github.css，按照上述方法修改即可。修改完成需要保存回压缩包。在打开压缩包修改的时候，必须关闭sublime，否则无法修改成功。

几个常用的markdown语法示例

标题

标题1=====#标题1##标题2###标题3

列表

###无序列表1* 列表1* 列表2* 列表3###无序列表2- 列表1- **列表2**- 列表3###有序列表1. 列表12. 列表23. 列表3

弹出式注释

把鼠标停留在**HTML**和**W3C**上看会发生什么。*[HTML]: Hyper Text Markup Language*[W3C]: World Wide Web Consortium

定义列表

Apple:   Pomaceous fruit of plants of the genus Malus in    the family Rosaceae.Orange:   The fruit of an evergreen tree of the genus Citrus.

代码片段

    ```python        #!python        # -*- coding: utf-8 -*-        from flask import Flask, render_template        app = Flask(__name__)        app.debug = APP_DEBUG        #homepage just for fun        @app.route('/')        def home():            return render_template('index.html')    ```

角注

Footnotes[^1] have a label[^@#$%] and the footnote's content.[^1]: This is a footnote content.[^@#$%]: A footnote on the label: "@#$%".

表格

First Header  | Second Header--------------|--------------Content Cell  | Content CellContent Cell  | Content Cell

警告

####hint类型的警告!!! hint "subject of hint"    Any number of other indented markdown elements.####note类型的警告!!! note "subject of note"    Any number of other indented markdown elements.

警告有多种类型，类型不同生成的html文档样式也不一样，可用的样式有 hint, attention, caution, danger, question, note。

强调

这是**黑体**写法这是*斜体*的写法

超链接

这是一个[链接](https://github.com/kamidox/blogs)这是另外一种[链接][1]的形式[1]: https://pythonhosted.org/Markdown/extensions/index.html

引用

> 引用的文字内容> 这是另外的引用内容

图片

![图片描述](https://raw.githubusercontent.com/kamidox/blogs/master/kamidox_icon.png)

目录

[TOC]

练习

1. 直接在配置好的sublime里新建一个readme.md，把上面的markdown语法拷贝进去练习一下。
2. 推荐一个做得相当不错的markdown在线编辑器马克飞象。
3. 本文就是用markdown编写的。右键点击这里，另存到本地即可。

最佳实践

Windows下可以使用sublime对markdown进行编辑预览。但Linux下要让sublime支持中文输入还需要折腾一番。个人认为最佳实践是这样的。

1. Windows下，使用sublime对markdown进行编辑，预览。
2. Linux下，直接使用gedit对markdown进行编辑。gedit的markdown语法高亮看起来非常舒服。编辑完成后，用sublime打开预览效果。