GH Actions/publish-wiki: auto-generate table of contents #6
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This commit adds steps to the workflow to auto-generate a GitHub wiki compatible table of contents in most wiki pages.
This reduces the risk of a TOC being out-of-date or containing incorrectly formatted links, as well as reduces the maintenance burden.
This action uses the `doctoc` pages to generate the table of contents and this can be tested locally using the same steps as used in the GH Actions workflow:
```
npm install -g doctoc
cp -v -a wiki _wiki
doctoc ./_wiki/ --github --maxlevel 4 --update-only
doctoc ./_wiki/Version-4.0-User-Upgrade-Guide.md --github --maxlevel 3 --update-only
```
Notes:
* The files are copied to a `_wiki` directory - which is `.gitignore`d - before pre-processing to reduce the risk of the source files being accidentally updated (and committed), which would undo the automation.
* The `--github` flag puts the TOC generation in GitHub compatible mode.
* The `--update-only` flag means that only markdown files containing the `<!-- START doctoc -->` and `<!-- END doctoc -->` markers will be updated and files without those markers will be left alone.
* By default, the TOC will contain all headers up to the indicated `--maxlevel`.
For the V 4.0 Dev upgrade guide, this looked weird, what with some "Upgrading" headers being at level 4 and some at level 5.
To mitigate this, a couple of headers have been turned into "bold phrases" instead.
Along the same lines, for the V 4.0 User upgrade guide, the level 4 headers were always "Upgrading". Those belong with their parent heading and IMO do not need to be separately called out in the TOC, which explains the second call to `doctoc` to overrule the TOC for that file specifically with a `--maxlevel 3` setting.
* The start/end markers have been added to all files which contained a TOC, except for one: `Reporting.md`.
The reason for this exception is that the section order in the file does not match the current TOC order, with the existing TOC order making sense from a TOC point of view, while the section order makes sense from a "types of reports most used" point of view.
Whether this page should be re-organized or not, is outside the scope of this PR.
To allow contributors to review the resulting pre-processed wiki files, the files are uploaded as an artifact when a PR dry-run is being executed and a comment is posted on the PR requesting the contributor to review the pre-processed files.
Includes adding a TOC to the Coding Standards Tutorial page and adding "back to top" links within the page.
Ref:
* https://github.com/thlorenz/doctoc
|
Thank you for your PR. Please review the resulting final markdown files via the created artifact. N.B.: the above link will automatically be updated when this PR is updated. |
|
Hmm... looks like the PR comment is posted with me as commenter because the |
|
Switching to use Maybe let's start with |
jrfnl
added a commit
that referenced
this pull request
Jul 17, 2025
In the original PR (#6), a Personal Access Token (PAT) was used, but that resulted in the comment being left as if coming from my account, which is misleading, which is why the `repo_token` was initially switched back to `secrets.GITHUB_TOKEN`, with a reminder that a test would need to be done with a PR coming from a fork to verify that the auto-comment would still work. As the first PR from a fork has now come in (#38), it has become clear that the auto-comment does not work with the default GitHub token, so this commit switches the `repo_token` back to the Personal Access Token and updates the message to make it clear I did not leave the comment. We'll still have to test (again) whether using the PAT works for PRs coming from forks. If not, we'll have to revisit this workflow step.
jrfnl
added a commit
that referenced
this pull request
Jul 17, 2025
In the original PR (#6), a Personal Access Token (PAT) was used, but that resulted in the comment being left as if coming from my account, which is misleading, which is why the `repo_token` was initially switched back to `secrets.GITHUB_TOKEN`, with a reminder that a test would need to be done with a PR coming from a fork to verify that the auto-comment would still work. As the first PR from a fork has now come in (#38), it has become clear that the auto-comment does not work with the default GitHub token, so this commit switches the `repo_token` back to the Personal Access Token and updates the message to make it clear I did not leave the comment. We'll still have to test (again) whether using the PAT works for PRs coming from forks. If not, we'll have to revisit this workflow step.
jrfnl
added a commit
that referenced
this pull request
Jul 17, 2025
In the original PR (#6), a Personal Access Token (PAT) was used, but that resulted in the comment being left as if coming from my account, which is misleading, which is why the `repo_token` was initially switched back to `secrets.GITHUB_TOKEN`, with a reminder that a test would need to be done with a PR coming from a fork to verify that the auto-comment would still work. As the first PR from a fork has now come in (#38), it has become clear that the auto-comment does not work with the default GitHub token, so this commit switches the `repo_token` back to the Personal Access Token and updates the message to make it clear I did not leave the comment. We'll still have to test (again) whether using the PAT works for PRs coming from forks. If not, we'll have to revisit this workflow step.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This commit adds steps to the workflow to auto-generate a GitHub wiki compatible table of contents in most wiki pages.
This reduces the risk of a TOC being out-of-date or containing incorrectly formatted links, as well as reduces the maintenance burden.
This action uses the
doctocpages to generate the table of contents and this can be tested locally using the same steps as used in the GH Actions workflow:Notes:
_wikidirectory - which is.gitignored - before pre-processing to reduce the risk of the source files being accidentally updated (and committed), which would undo the automation.--githubflag puts the TOC generation in GitHub compatible mode.--update-onlyflag means that only markdown files containing the<!-- START doctoc -->and<!-- END doctoc -->markers will be updated and files without those markers will be left alone.--maxlevel. For the V 4.0 Dev upgrade guide, this looked weird, what with some "Upgrading" headers being at level 4 and some at level 5. To mitigate this, a couple of headers have been turned into "bold phrases" instead. Along the same lines, for the V 4.0 User upgrade guide, the level 4 headers were always "Upgrading". Those belong with their parent heading and IMO do not need to be separately called out in the TOC, which explains the second call todoctocto overrule the TOC for that file specifically with a--maxlevel 3setting.Reporting.md. The reason for this exception is that the section order in the file does not match the current TOC order, with the existing TOC order making sense from a TOC point of view, while the section order makes sense from a "types of reports most used" point of view. Whether this page should be re-organized or not, is outside the scope of this PR.To allow contributors to review the resulting pre-processed wiki files, the files are uploaded as an artifact when a PR dry-run is being executed and a comment is posted on the PR requesting the contributor to review the pre-processed files.
Includes adding a TOC to the Coding Standards Tutorial page and adding "back to top" links within the page.
Ref: