ref: 0197e6f23c0db6baf11aa1e610521f78b6352605
dir: /tools/toc.py/
#!/usr/bin/env python3 # -*- coding: utf-8 -*- """ Usage: python3 toc.py [-n] files.md... Replace a "## TOC" heading in a Markdown file with a table of contents, generated from the other headings in the file. Supports multiple files. Headings must start with "##" signs to be detected. """ import sys import re from collections import namedtuple toc_name = 'Contents' valid_toc_headings = {'## TOC', '##TOC'} TocItem = namedtuple('TocItem', ['name', 'anchor', 'level']) punctuation_regexp = re.compile(r'[^\w\- ]+') def name_to_anchor(name): # GitHub's algorithm for generating anchors from headings # https://github.com/jch/html-pipeline/blob/master/lib/html/pipeline/toc_filter.rb anchor = name.strip().lower() # lowercase anchor = re.sub(punctuation_regexp, '', anchor) # remove punctuation anchor = anchor.replace(' ', '-') # replace spaces with dash return anchor def get_toc_index(lines): toc_index = None for i, line in enumerate(lines): if line.rstrip() in valid_toc_headings: toc_index = i break return toc_index def get_toc_items(lines, toc_index): for i, line in enumerate(lines): if i <= toc_index: continue if line.startswith('##'): name = line.lstrip('#') level = len(line) - len(name) - len('##') name = name.strip() anchor = name_to_anchor(name) yield TocItem(name, anchor, level) def toc_string(toc_items): lines = ['## %s' % toc_name, ''] for name, anchor, level in toc_items: padding = ' ' * level line = '%s- [%s](#%s)' % (padding, name, anchor) lines.append(line) return '\n'.join(lines) + '\n' def add_toc(filename): with open(filename, 'r', encoding='utf-8') as f: lines = f.readlines() toc_index = get_toc_index(lines) if toc_index is None: return None # no TOC heading toc_items = list(get_toc_items(lines, toc_index)) if not toc_items: return False # no content headings with open(filename, 'w', encoding='utf-8') as f: for i, line in enumerate(lines): if i == toc_index: f.write(toc_string(toc_items)) else: f.write(line) return True # OK def main(): if len(sys.argv) < 2: print('*** ERROR: No filenames specified') print(__doc__) exit(1) for filename in sys.argv[1:]: print(filename) result = add_toc(filename) if result is None: print('*** WARNING: No "## TOC" heading found') elif result is False: print('*** WARNING: No content headings found') else: print('OK') if __name__ == '__main__': main()