文件标题自动生成 SUMMARY.md
文章目录
文件标题自动生成 SUMMARY.md
1. 背景
2. 需求
3. 代码
4. demo
4.1 `SUMMARY.md` 添加文章
4.2 `SUMMARY.md` 添加目录
4.3 `SUMMARY.md` 添加子目录
4.4 `SUMMARY.md` 覆盖
4.5 `SUMMARY.md` 追加
4.6 `SUMMARY.md`忽略
4.7 `SUMMARY.md`替代
4.8 文章排序
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
功能：
- 可以通过
-o覆盖已有的SUMMARY.md - 新生成一个
SUMMARY-GitBook-auto-summary.md - 还可以通过-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)
参考：
