OPSEXP-2939: add a markdown toc generation action (#825)

Co-authored-by: Giovanni Toraldo <[email protected]>

.github/actions/md-toc/action.yml

@@ -0,0 +1,68 @@
+name: Markdown ToC Generator
+description: Generate a Table of Contents from a Markdown file
+inputs:
+  md_toc_version:
+    description: Markdown Table of Contents Package version
+    required: false
+    default: 1.2.0
+  md_src:
+    description: |
+      Markdown file(s) to generate Table of Contents for. It can be a list of
+      space separated files or a glob pattern relative to the repository root.
+    required: true
+  depth:
+    description: Depth of Table of Contents
+    required: false
+    default: '2'
+  dry_run:
+    description: Skip destructive actions
+    required: false
+    default: 'false'
+  append:
+    description: >-
+      A string to append to Table of Contents (e.g. you may want to append the
+      sha of the commit toc was added on top of?)
+    required: false
+    default: ''
+  bullets:
+    description: Bullets to use for Table of Contents ("*", "-" or "+")
+    required: false
+    default: ''
+  node_version:
+    description: Node.js version to install (false means do not install)
+    required: false
+    default: '20'
+runs:
+  using: 'composite'
+  steps:
+    - uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
+      if: ${{ inputs.node_install }}
+      with:
+        node-version: ${{ inputs.node_version }}
+    - name: Install Markdown ToC node package
+      run: npm install -g markdown-toc@${{ inputs.md_toc_version }}
+      shell: bash
+    - name: Generate Table of Contents
+      env:
+        MDTOC_IARG: ${{ inputs.dry_run == 'false' && '-i' || '' }}
+        MDTOC_BARG: ${{ inputs.bullets != '' && format('--bullets {0}', inputs.bullets) || '' }}
+      run: |
+        export MDTOC_ARGS="${{ env.MDTOC_IARG }} ${{ env.MDTOC_BARG }}"
+        for f in ${{ inputs.md_src }}; do
+          if [ -f $f ]; then
+            markdown-toc $MDTOC_ARGS \
+              --maxdepth ${{ inputs.depth }} \
+              --append "${{ inputs.append }}" $f && \
+            echo "Table of Contents successfully generated in ${{ inputs.md_src }}"
+          else
+            echo "File $f not found.. Skipping!"
+          fi
+        done
+      shell: bash
+    - name: Autocommit changes
+      if: inputs.dry_run == 'false'
+      uses: stefanzweifel/git-auto-commit-action@8621497c8c39c72f3e2a999a26b4ca1b5058a842 # v5.0.1
+      with:
+        commit_message: Auto update TOC in ${{ inputs.md_src }}
+        disable_globbing: true
+        file_pattern: ${{ inputs.md_src }}

.github/dependabot.yml

@@ -385,6 +385,14 @@ updates:
       catch-all:
         patterns:
           - "*"
+  - package-ecosystem: "github-actions"
+    directory: "/.github/actions/md-toc"
+    schedule:
+      interval: "weekly"
+    groups:
+      catch-all:
+        patterns:
+          - "*"
   - package-ecosystem: "github-actions"
     directory: "/.github/actions/nexus-move-artifacts"
     schedule:

.pre-commit-hooks.yaml

@@ -28,3 +28,13 @@
   entry: bash -c 'find . -name Chart.yaml | xargs -I% bash -c "dirname %" | xargs -t -I% bash -c "helm template % | kubepug --error-on-deprecated --error-on-deleted --input-file=-"'
   language: system
   pass_filenames: false
+- id: md-toc
+  name: Markdown Table of Contents
+  entry: >-
+    bash -eu -o pipefail -c
+    "MDTOC_ARGS=\"\";
+    for f in $@; do
+      [[ \"x$f\" = x--* ]] && MDTOC_ARGS=\"$f $MDTOC_ARGS\" && continue;
+      [ -f \"$f\" ] && markdown-toc $MDTOC_ARGS -i $f;
+    done"
+  language: system

docs/README.md

@@ -73,6 +73,7 @@ Here follows the list of GitHub Actions topics available in the current document
     - [maven-deploy-file](#maven-deploy-file)
     - [maven-release](#maven-release)
     - [maven-update-pom-version](#maven-update-pom-version)
+    - [md-toc](#md-toc)
     - [nexus-move-artifacts](#nexus-move-artifacts)
     - [pre-commit](#pre-commit)
     - [process-coverage-report](#process-coverage-report)
@@ -1102,6 +1103,28 @@ Updates pom files to the provided version
         version: 1.0.0-alpha.1
 ```
 
+### md-toc
+
+Generates a Markdown table of contents for a file.
+
+```yaml
+      - uses: Alfresco/alfresco-build-tools/.github/actions/md-toc@ref
+        with:
+          md_src: 'LICENSE.md README.md docs/*.md'
+          bullets: '-'
+          depth: '4'
+          md_toc_version: 1.2.0
+          node_install: 'false'
+```
+
+For ToC to be inserted in your file, it needs to contain the HTML comment below:
+
+```markdown
+## Table of Contents
+
+<!-- toc -->
+```
+
 ### nexus-move-artifacts
 
 Moves artifacts from one repository to another on Nexus 3, identified by a particular group and version.

version.txt

@@ -1 +1 @@
-v8.5.0
+v8.6.0