使用Python从Markdown文档中自动生成标题导航

概述###

Markdown 很适合于技术写作，因为技术写作并不需要花哨的排版和内容， 只要内容生动而严谨，文笔朴实而优美。

为了编写对读者更友好的文章，有必要生成文章的标题导航，让读者有个预期的阅读概览。当文章标题比较多时，手工去编写导航锚点比较费时，因此决定使用Python解析Markdown文档自动生成标题导航。

知识与思路###

写过Markdown的人知道，Markdown的标题是使用一到六个# 左右包围住标题文字，而锚点是 [标题](#标题)。 比如 ## 知识与思路 ## ，锚点连接是 [知识与思路](#知识与思路)。标题文字允许包含空格，不过最好不要用空格或特殊不可打印字符，因为在网页上点击带锚点的链接时可能失效，并且网站对Markdown锚点的支持可能有特殊规则，比如博客园会将标题中的大写字母自动转成小写字母，并且对于有空格的标题可能无法链接到锚点。

这样，就需要解析标题行，从中提取出标题并生成锚点链接。通常使用正则表达式来匹配和提取文本内容。此外，为了排版，也要根据标题的级别生成相应的缩进。考虑到段落中很可能含有#字符，因此标题最好从第二级开始，不超过四级。

标题行的正则表达式是：

\s*(#{2,6})\s*(.*?)\s*(?:\1)\s+

知识点：

1. 2-6 个#号使用 #{2,6} 匹配；
2. 由于行起始和标题前后都可能含有空格，因此需要使用\s*来兼容；行末尾至少有个换行符，因此要使用 \s+；
3. 使用(subregex)捕获 subregex 匹配的文本， 使用 \1 表示后面与前面对应的被匹配的分组文本, 使用 (?:subregex) 表示匹配 subregex 的文本，但在捕获分组时忽略，不作为提取内容；
4. 使用 (.*?) 匹配标题内容， ？ 表示非贪婪模式，避免将 # 也包含到标题中；
5. 标题的缩进比较简单，第二级的不缩进，第N级缩进 (N-2)个指定字符，这里字符选定为中文空格  
6. 程序会接受一系列 Markdown 文档的文件路径参数，并输出对应于每个文件的导航文本；由于参数比较简单，就不使用 argparse 这样的参数解析模块了；
7. 使用： python mdnav.py filename1 filename2 ... filenameN

代码实现###

#!/usr/bin/python
#_*_encoding:utf-8_*_

##########################################################################
# mdnav.py: Generate nav anchors for given markdown files
# usage:  python mdnav.py md_filename1 md_filename2 ... md_filenameN
##########################################################################

import re
import sys

mdTitleRegex = r'\s*(#{2,6})\s*(.*?)\s*(?:\1)\s+'
mdTitlePatt = re.compile(mdTitleRegex)

def parseLineByRegex(line, regex_patt):
    m = regex_patt.match(line)
    return m.groups() if m else ()

def outputAnchor(titleTuple):
    if len(titleTuple) == 2:
        intents = ' ' * (len(titleTuple[0])-2)
        title = titleTuple[1]
        anchor = '[%s](#%s)' % (title, title)
        print intents,anchor

def procLine(line):
    outputAnchor(parseLineByRegex(line, mdTitlePatt))

def help():
    print '%s usage: need at least one param as markdown filename' % sys.argv[0]
    print 'python %s filename1 filename2 ... filenameN' % sys.argv[0]

if __name__ == '__main__':
    if len(sys.argv) < 2:
        help()
        exit(1)
    for ind in range(1, len(sys.argv)):
        filename = sys.argv[ind]
        print 'file: ', filename
        with open(filename) as mdtext:
            map(procLine, mdtext.readlines())