1. 背景

我们了解 gitbook plugin summary 自动生成 summary.md 文件内容
这是book sm命令依赖markdown文章名字组成目录结构的样子。

$ npm install gitbook-plugin-summary
$ npm install -g gitbook-summary
$ book sm
Finished, generated 'SUMMARY.md' successfully.
$ cat SUMMARY.md 
# Git Handbook

- Git
  * [2 Git Practice](Git/2_git_practice.md)
- Gitbook
  * [1 Gitbook Start](Gitbook/1_gitbook_start.md)
  * [2 Gitbook Plugin Summary](Gitbook/2_gitbook-plugin-summary.md)
  * [3 Github Pages Gitbook](Gitbook/3_github_pages_gitbook.md)
- Github
  * [1 Github Introduce](Github/1_github_introduce.md)
  * [2 Github Local Pull Github](Github/2_github_local_pull_github.md)
  * [3 Github Action](Github/3_github_action.md)
  * [4 Github Page](Github/4_github_page.md)
- Gitlab
  * [1 Gitlab Start](Gitlab/1_gitlab_start.md)
  * [2 Gitlab Deploy](Gitlab/2_gitlab_deploy.md)
  * [3 Gitlab Config](Gitlab/3_gitlab_config.md)
  * [4 Gitlab Runner Deploy](Gitlab/4_gitlab_runner_deploy.md)
  * [5 Gitlab Runner Management](Gitlab/5_gitlab_runner_management.md)

但我的需求是可以依据文章标题来生成整个结构，因为如果你有一批大量的markdown文章一个一个手写改动、添加、删除都是一件非常麻烦的事。

我发现来自mofhu/GitBook-auto-summary的功能接近我的需求。

 $ python3 gitbook-auto-summary.py -h
usage: gitbook-auto-summary.py [-h] [-o] [-a] directory

positional arguments:
  directory        the directory of your GitBook root

optional arguments:
  -h, --help       show this help message and exit
  -o, --overwrite  overwrite on SUMMARY.md
  -a, --append     append on SUMMARY.md

功能：

1. 可以通过-o覆盖已有的SUMMARY.md
2. 新生成一个SUMMARY-GitBook-auto-summary.md
3. 还可以通过-a实现追加内容。

2. 需求

但这离我渴望的需求还差一点点，那就是当文章内容存在标题，我更选择它来做链接名片，当不存在标题再去依赖文章名字（英文或中文）作为链接名片。并且在gitbook-auto-summary.py脚本当前目录我还可以让一些无关的目录作为例外。比如：node_modules

我把它实现了。

3. 代码

代码：@ghostwritten/GitBook-auto-summary

# -*- coding: utf-8 -*-
# Author Frank Hu & zong xun
# GitBook auto summary
# summary all .md files in a GitBook folder

import argparse
import os
import re

teshu_list = ['_book', 'node_modules', 'img']

def output_markdown(dire, base_dir, output_file, append, iter_depth=0):
    """Main iterator for get information from every file/folder

    i: directory, base directory(to calulate relative path), 
       output file name, iter depth.
    p: Judge is directory or is file, then process .md/.markdown files.
    o: write .md information (with identation) to output_file.
    """
    top_list = os.listdir(dire)
    for i in top_list:
       if i in teshu_list:
          top_list.remove(i)

    for filename in sort_dir_file(top_list, base_dir): 
        # add list and sort
#        print('Processing ', filename) # output log
        file_or_path = os.path.join(dire, filename)
        if os.path.isdir(file_or_path): #is dir
            if mdfile_in_dir(file_or_path):
                # if there is .md files in the folder, output folder name
                output_file.write('  ' * iter_depth + '- ' + filename + '\n')
                print('  ' * iter_depth + '- ' + filename + '\n')
                output_markdown(file_or_path, base_dir, output_file, append, 
                                iter_depth + 1) # iteration
        else: # is file
            if is_markdown_file(dire, base_dir,filename): 
            # re to find target markdown files, $ for matching end of filename
                if (filename not in ['SUMMARY.md', 
                                     'SUMMARY-GitBook-auto-summary.md'] 
                    or iter_depth != 0): # escape SUMMARY.md at base directory
                    output_file.write('  ' * iter_depth + 
                        '- [{}]({})\n'.format(write_md_filename(dire, base_dir,filename, 
                                                                append), 
                            os.path.join(os.path.relpath(dire, base_dir), 
                                         filename)))
                    print('  ' * iter_depth + '- [{}]({})\n'.format(write_md_filename(dire, base_dir,filename, append), os.path.join(os.path.relpath(dire, base_dir),filename)))
                    # iter depth for indent, relpath and join to write link.

def mdfile_in_dir(dire):
    """Judge if there is .md file in the directory

    i: input directory
    o: return Ture if there is .md file; False if not.
    """
    for root, dirs, files in os.walk(dire):
        for filename in files:
            if re.search('.md$|.markdown$', filename):
                return True
    return False


def markdown_title_name(dire, base_dir,filename):
    path_filename = os.path.join(os.path.relpath(dire, base_dir), filename)
    with open(path_filename) as f:
        firstline = f.readline().rstrip()

    #if not firstline.isalnum():
    if firstline == '' or firstline == '---':
      title = filename.split('.',1)[0]
    else:
      title = firstline.lower().strip()
      for i in range(0, len(title)):
        if not title[i].isalnum():
           title = title[0:i] + ' ' + title[i+1:]
      while '--' in title:
         title = title.replace('--', ' ')
    title = title.strip(' ')
    return title

def is_markdown_file(dire, base_dir,filename):
    """ Judge if the filename is a markdown filename

    i: filename
    o: filename without '.md' or '.markdown'
    """
    if (filename not in ['SUMMARY.md','SUMMARY-GitBook-auto-summary.md']):
        match = re.search('.md$|.markdown$', filename)
        if not match:
           return False
        elif len(match.group()) is len('.md'):
           md_title = markdown_title_name(dire, base_dir,filename)
           return md_title
        elif len(match.group()) is len('.markdown'):
           md_title = markdown_title_name(dire, base_dir,filename)
           return md_title

def sort_dir_file(listdir, dire):
    # sort dirs and files, first files a-z, then dirs a-z
    list_of_file = []
    list_of_dir = []
    for filename in listdir:
        if os.path.isdir(os.path.join(dire, filename)):
            list_of_dir.append(filename)
        else: 
            list_of_file.append(filename)
    for dire in list_of_dir:
        list_of_file.append(dire)
    return list_of_file  

def write_md_filename(dire, base_dir,filename, append):
    """ write markdown filename

    i: filename and append
    p: if append: find former list name and return
       else: write filename
    """
    if append:
        for line in former_summary_list:
            if re.search(filename, line):
                s = re.search('\[.*\]\(',line)
                return s.group()[1:-2]
                
        else:
            return is_markdown_file(dire, base_dir,filename)
    else:
        return is_markdown_file(dire, base_dir,filename)

def main():
    parser = argparse.ArgumentParser()
    parser.add_argument('-o', '--overwrite', 
                        help='overwrite on SUMMARY.md', 
                        action="store_true")
    parser.add_argument('-a', '--append', 
                        help='append on SUMMARY.md', 
                        action="store_true")
    parser.add_argument('directory', 
                        help='the directory of your GitBook root')
    args = parser.parse_args()
    overwrite = args.overwrite
    append = args.append
    dir_input = args.directory

    # print information
    print('GitBook auto summary:', dir_input, end = ' ')
    if overwrite:
        print('--overwrite', end = ' ')
    if append and os.path.exists(os.path.join(dir_input, 'SUMMARY.md')): 
        #append: read former SUMMARY.md
        print(os.listdir(dir_input))
        print('--append', end = ' ')
        global former_summary_list
        with open(os.path.join(dir_input, 'SUMMARY.md')) as f:
            former_summary_list = f.readlines()
            f.close()
    print()
    # output to flie
    if (overwrite == False and 
        os.path.exists(os.path.join(dir_input, 'SUMMARY.md'))):
        # overwrite logic
        filename = 'SUMMARY-GitBook-auto-summary.md'
    else:
        filename = 'SUMMARY.md'
    output = open(os.path.join(dir_input, filename), 'w')
    output.write('# Summary\n\n')
    output_markdown(dir_input, dir_input, output, append)

    print('GitBook auto summary finished:) ')
    return 0

if __name__ == '__main__':
    main()

我们验证它的效果。

4. demo

4.1 SUMMARY.md 添加文章

添加README.md

$ ls
gitbook-auto-summary.py  README.md
root@yourdomain:~/example/summary-demo# python3 gitbook-auto-summary.py .
GitBook auto summary: . 
- [序言](./README.md)

GitBook auto summary finished:) 
root@yourdomain:~/example/summary-demo# ls
gitbook-auto-summary.py  README.md  SUMMARY.md
root@yourdomain:~/example/summary-demo# cat SUMMARY.md 
# Summary

- [序言](./README.md)

4.2 SUMMARY.md 添加目录

创建Git目录，并新增格式.md与.markdown格式文章。

$ ls Git/
1_git_introduce.markdown  2_git_practice.md
//查看是否有标题
$ head -n 1 Git/1_git_introduce.markdown 
# git 介绍 
$ head -n 1 Git/2_git_practice.md 
# git 实践

$ python3 gitbook-auto-summary.py .
GitBook auto summary: . 
- [序言](./README.md)

- Git

  - [git 介绍](Git/1_git_introduce.markdown)

  - [git 实践](Git/2_git_practice.md)

GitBook auto summary finished:) 
root@yourdomain:~/example/summary-demo# ls
Git  gitbook-auto-summary.py  README.md  SUMMARY-GitBook-auto-summary.md  SUMMARY.md

注意默认情况下（python3 gitbook-auto-summary.py .）当已存在 SUMMARY.md，脚本不会破坏已有SUMMARY.md。而是会生成新的文件：SUMMARY-GitBook-auto-summary.md

$ cat SUMMARY-GitBook-auto-summary.md 
# Summary

- [序言](./README.md)
- Git
  - [git 介绍](Git/1_git_introduce.markdown)
  - [git 实践](Git/2_git_practice.md)

$ cat SUMMARY.md 
# Summary

- [序言](./README.md)

4.3 SUMMARY.md 添加子目录

添加子目录并且添加一篇markdown文章。

ls Git/
1_git_introduce.markdown  2_git_practice.md  3_git_remote_repo.md  git_command
root@yourdomain:~/example/summary-demo# ls Git/git_command/
2_git_command.md
root@yourdomain:~/example/summary-demo# head -n 1 Git/git_command/2_git_command.md 
# git 命令

执行如下：

$ python3 gitbook-auto-summary.py -o .
$ cat SUMMARY.md 
# Summary

- [序言](./README.md)
- Git
  - [git 介绍](Git/1_git_introduce.markdown)
  - git_command
    - [git 命令](Git/git_command/2_git_command.md)
  - [git 实践](Git/2_git_practice.md)

4.4 SUMMARY.md 覆盖

如果你只想覆盖SUMMARY.md 而已。可以python3 gitbook-auto-summary.py -o .实现。

$ python3 gitbook-auto-summary.py -o  .
GitBook auto summary: . --overwrite 
- [序言](./README.md)

- Git

  - [git 介绍](Git/1_git_introduce.markdown)

  - [git 实践](Git/2_git_practice.md)

GitBook auto summary finished:) 
root@yourdomain:~/example/summary-demo# cat SUMMARY.md 
# Summary

- [序言](./README.md)
- Git
  - [git 介绍](Git/1_git_introduce.markdown)
  - [git 实践](Git/2_git_practice.md)

有些情况，你可能认为覆盖比较危险，但又不想备份它，只想在原有的基础上追加内容。我们可以python3 gitbook-auto-summary.py -a .实现。

4.5 SUMMARY.md 追加

在Git目录新添了一篇文章。

$ ls Git/
1_git_introduce.markdown  2_git_practice.md  3_git_remote_repo.md

并且我手动改一下 SUMMARY.md 内容做一个标记。把git 介绍改成git xxx

# Gitbook-Handbook

- [序言](./README.md)
- Git
  - [git xxx](Git/1_git_introduce.markdown)
  - [git 实践](Git/2_git_practice.md)

ls
Git  gitbook-auto-summary.py  README.md  SUMMARY.md

执行python3 gitbook-auto-summary.py -a .，SUMMARY.md修改的xxx并没有被覆盖掉。

$ python3 gitbook-auto-summary.py -a  .
$ cat SUMMARY-GitBook-auto-summary.md 
# Summary

- [序言](./README.md)
- Git
  - [git xxx](Git/1_git_introduce.markdown)
  - [github 管理远程仓库](Git/3_git_remote_repo.md)
  - [git 实践](Git/2_git_practice.md)

如果直接在SUMMARY.md追加。执行如下：

$ python3 gitbook-auto-summary.py -a -o  .
$ cat SUMMARY.md 
# Summary

- [序言](./README.md)
- Git
  - [git xxx](Git/1_git_introduce.markdown)
  - [github 管理远程仓库](Git/3_git_remote_repo.md)
  - [git 实践](Git/2_git_practice.md)

当去掉-a参数，覆盖重新生成。

$ python3 gitbook-auto-summary.py  -o  .
$ cat SUMMARY.md 
# Summary

- [序言](./README.md)
- Git
  - [git 介绍](Git/1_git_introduce.markdown)
  - [github 管理远程仓库](Git/3_git_remote_repo.md)
  - [git 实践](Git/2_git_practice.md)

4.6 SUMMARY.md忽略

我们创建一个目录img，也许你会用来存储图片。

$ mkdir img

$ ls
Git  gitbook-auto-summary.py  img  README.md  SUMMARY.md

修改代码第十行列表添加'img'

 ignore_list = ['_book', 'node_modules', 'img']

执行如下：

$ python3 gitbook-auto-summary.py  -o  .
$ cat SUMMARY.md 
# Summary

- [序言](./README.md)
- Git
  - [git 介绍](Git/1_git_introduce.markdown)
  - [github 管理远程仓库](Git/3_git_remote_repo.md)
  - [git 实践](Git/2_git_practice.md)

大纲并没有收到影响。因为img目录已被当作例外。

4.7 SUMMARY.md替代

当markdown没有标题的时候，也就是说第一行内容为空，我们判断认定为标题不存在。“# xxxx”在其他行并不会被发现。这个时候我们会默认以文章名字作为链接名片。

我们把Git/git_commnad/2_git_command.md文章第一行的标题去掉或者下移一行。

$ head -n 2 Git/git_command/2_git_command.md 
<空行>
# git 命令

执行如下：

$ python3 gitbook-auto-summary.py -o .
$ cat SUMMARY.md 
# Summary

- [序言](./README.md)
- Git
  - [git 介绍](Git/1_git_introduce.markdown)
  - git_command
    - [2_git_command](Git/git_command/2_git_command.md)
  - [github 管理远程仓库](Git/3_git_remote_repo.md)
  - [git 实践](Git/2_git_practice.md)

这也是最初book sm命令结果的样子。

4.8 文章排序

这是超过10数量的文章。

$  ls Docker-Swarm/
docker_swarm_10_maintenance_mode.md  docker_swarm_6_healthcheck.md
docker_swarm_1_start.md              docker_swarm_7_update.md
docker_swarm_2_network.md            docker_swarm_8_UI_Portainer.md
docker_swarm_3_load_balancing.md     docker_swarm_9_docker-compose_deploy_app.md
docker_swarm_4_encrypted_network.md  README.md
docker_swarm_5_secrets.md            SUMMARY.md

book sm执行的效果是这样，docker_swarm_10_maintenance_mode.md并没有按照正常的顺序排在docker_swarm_9_docker-compose_deploy_app.md的后面。

- [Docker Swarm](Docker-Swarm/README.md)
  * [Docker Swarm 1 Start](Docker-Swarm/docker_swarm_1_start.md)
  * [Docker Swarm 10 Maintenance Mode](Docker-Swarm/docker_swarm_10_maintenance_mode.md)
  * [Docker Swarm 2 Network](Docker-Swarm/docker_swarm_2_network.md)
  * [Docker Swarm 3 Load Balancing](Docker-Swarm/docker_swarm_3_load_balancing.md)
  * [Docker Swarm 4 Encrypted Network](Docker-Swarm/docker_swarm_4_encrypted_network.md)
  * [Docker Swarm 5 Secrets](Docker-Swarm/docker_swarm_5_secrets.md)
  * [Docker Swarm 6 Healthcheck](Docker-Swarm/docker_swarm_6_healthcheck.md)
  * [Docker Swarm 7 Update](Docker-Swarm/docker_swarm_7_update.md)
  * [Docker Swarm 8 UI Portainer](Docker-Swarm/docker_swarm_8_UI_Portainer.md)
  * [Docker Swarm 9 Docker Compose Deploy App](Docker-Swarm/docker_swarm_9_docker-compose_deploy_app.md)

那看我的。docker_swarm_10_maintenance_mode.md按照正常的顺序排在docker_swarm_9_docker-compose_deploy_app.md的后面。

$ python3 gitbook-auto-summary.py .
$ cat SUMMARY-GitBook-auto-summary.md
# Summary

* [summary](./Overview.md)
* [序言](./README.md)
- Docker-Swarm
  * [docker swarm 介绍](Docker-Swarm/README.md)
  * [docker swarm 快速入门](Docker-Swarm/docker_swarm_1_start.md)
  * [docker swarm 网络](Docker-Swarm/docker_swarm_2_network.md)
  * [docker swam 集群实现负载均衡](Docker-Swarm/docker_swarm_3_load_balancing.md)
  * [docker swarm 创建加密覆盖网络](Docker-Swarm/docker_swarm_4_encrypted_network.md)
  * [docker swarm 管理 secrets](Docker-Swarm/docker_swarm_5_secrets.md)
  * [docker swarm 健康检查](Docker-Swarm/docker_swarm_6_healthcheck.md)
  * [dcoker swarm 更新](Docker-Swarm/docker_swarm_7_update.md)
  * [docker swarm 部署界面 ui portainer](Docker-Swarm/docker_swarm_8_UI_Portainer.md)
  * [docker swarm 通过 docker compose 部署应用](Docker-Swarm/docker_swarm_9_docker-compose_deploy_app.md)
  * [docker swarm 维护模式](Docker-Swarm/docker_swarm_10_maintenance_mode.md)