Github actions workflow to generate custom TOC

Background

Other than writing code, I have been using github for storing and organizing my daily notes. Github allows simplicity and flexibility to work with markdown, further it has the ability to version the files and view them across multiple devices. But as the total number of the file grows navigation becomes a bottleneck. To tackle this issue I’ve setup CI to generate a TOC(table of content) in the README so that I can quickly access a file from the README itself. I am going to setup a github actions workflow and make it generate the table of contents automatically for your project.

Workflow

Github Actions enables us to create workflows (like CI/CD capabilities) that can be integrated directly into our github code repository and runs on github hosted environments. These workflows are triggered automatically on occurrence of some event.

I have all the code and files committed in this demo github repository toc-demo. This is how the file structure for the example project looks like.

The github actions workflow is defined in a yaml file so we will create a file .github/workflows/action.yml.

We will write a script that can generate the table of contents and then commit the changes and push! We will automate this workflow using the github actions.

Workflow file

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

name: toc-workflow-demo
on:
  push:
    branches: [ main ]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: checkout repo content
        uses: actions/checkout@v2
      - name: setup python
        uses: actions/setup-python@v2
        with:
          python-version: 3.8
      - name: execute py script
        run: |
                    python script.py
      - name: commit changes
        run: |
          git config user.name github-actions
          git config user.email github-actions@github.com
          echo `git add . && git commit -m "Auto generated commit"`
          echo `git push`          
      - name: Update Status
        run: |
          echo Updated Index successfully,
          echo Auto commit changes          

Summarizing the action file:

• the job is triggered when changes are pushed on to the main branch.
• the steps explained:
  • the actions/checkout@v2 checks-out the repository toc-workflow-demo.
  • the actions/setup-python@v2 setups python v3.8 in our actions environment.
  • the job runs a script script.py to generate TOC and write to a file
  • the end step is to commit the changes script made and push them to github.

Script

To generate TOC we require the name and path of all files. This python script reads through all files in the directory and generates a table of content in a tree hierarchy format. You can modify this script to create what fits you best.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

import os
             
f=open('README.md','w+')
f.write('# Notes')
f.write('\n\n\n')
startpath = './notes'

for root, dirs, files in os.walk(startpath):
    if root is not startpath:
      level = root.replace(startpath, '').count(os.sep) -1
      indent = ' ' * 2 * (level)
      f.write('{}- {}'.format(indent, os.path.basename(root)))
      f.write('\n')
      subindent = ' ' * 2 * (level + 1)
      for file in files:
        path = os.path.join(root,file)
        f.write("{}- [{}]({})".format(subindent,file[:-3],path))
        f.write('\n')

Conclusion

Once all the code changes are committed and code is pushed to github. Github actions will run the jobs and auto-commit the table of content to project README. The following table of content has been generated by the github actions in the demo project. We can click on the file name to navigate to the file.

Next time any new file is added, removed or modified and committed to github, github actions will take care of updating the TOC.