GH Actions/publish-wiki: auto-generate table of contents

jrfnl · jrfnl · commit d0f9056dbbaf · 2025-07-13T06:34:13.000+02:00
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 ``` * 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 `` and `` 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. 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. Ref: * https://github.com/thlorenz/doctoc
diff --git a/.github/workflows/publish-wiki.yml b/.github/workflows/publish-wiki.yml
@@ -31,11 +31,53 @@ jobs:
     permissions:
       # Needed for the commit to the wiki.
       contents: write
+      # Needed for the PR comment.
+      pull-requests: write
 
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
 
+      - name: Install DocToc table of contents generator
+        run: npm install -g doctoc
+
+      - name: Copy wiki files to temporary location
+        shell: bash
+        run: cp -v -a wiki _wiki
+
+      - name: Update tables of contents
+        run: doctoc ./_wiki/ --github --maxlevel 4 --update-only
+
+      - name: Re-run tables of contents with different settings for specific file
+        run: doctoc ./_wiki/Version-4.0-User-Upgrade-Guide.md --github --maxlevel 3 --update-only
+
+      # Retention is normally 90 days, but this artifact is only to help with reviewing PRs,
+      # especially when new output blocks are added or the (workflow) code for existing ones
+      # is updated. All in all, no need to keep the artifact for more than a few days.
+      - name: "[PR only] Upload the preprocessed wiki files as an artifact"
+        if: ${{ github.event_name == 'pull_request' }}
+        id: artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: wiki-files
+          path: ./_wiki
+          if-no-files-found: error
+          retention-days: 10
+
+      - name: "[PR only] Post comment to review artifact"
+        if: ${{ github.event_name == 'pull_request' }}
+        uses: mshick/add-pr-comment@v2
+        with:
+          repo-token: ${{ secrets.COMMENT_ON_PRS_TOKEN }}
+          message: |
+            Thank you for your PR.
+            A dry-run has been executed on your PR, executing all markdown pre-processing for the wiki files.
+
+            Please review the resulting final markdown files via the [created artifact](${{ steps.artifact.outputs.artifact-url }}).
+            This is especially important when adding new pages.
+
+            _N.B.: the above link will automatically be updated when this PR is updated._
+
       - name: Check GitHub Git Operations status
         uses: crazy-max/ghaction-github-status@v4
         with:
@@ -47,7 +89,7 @@ jobs:
           COMMIT_MSG: ${{ github.event.head_commit.message }}
         with:
           strategy: 'clone'
-          path: 'wiki/'
+          path: '_wiki/'
           commit-message: ${{ env.COMMIT_MSG }}
           # repository: PHPCSStandards/PHP_CodeSniffer
           # token: ${{ secrets.PHPCS_PUSH_TO_WIKI_TOKEN }}
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1 @@
+_wiki/
diff --git a/wiki/About-Standards-for-PHP_CodeSniffer.md b/wiki/About-Standards-for-PHP_CodeSniffer.md
@@ -1,15 +1,7 @@
 ## Table of contents
 
-* [A Project ruleset or a standard ?](#a-project-ruleset-or-a-standard-)
-* [How does PHP_CodeSniffer determine which standard or ruleset to apply ?](#how-does-php_codesniffer-determine-which-standard-or-ruleset-to-apply-)
-* [About standards](#about-standards)
-* [Creating an external standard for PHP_CodeSniffer](#creating-an-external-standard-for-php_codesniffer)
-* [Creating new rules](#creating-new-rules)
-    * [Naming conventions](#naming-conventions)
-        * [1. Directory structure](#1-directory-structure)
-        * [2. Sniff file name](#2-sniff-file-name)
-        * [3. Namespace and class name](#3-namespace-and-class-name)
-        * [Examples](#examples)
+<!-- START doctoc -->
+<!-- END doctoc -->
 
 ***
 
diff --git a/wiki/Advanced-Usage.md b/wiki/Advanced-Usage.md
@@ -1,24 +1,7 @@
 ## Table of contents
 
-* [Specifying Valid File Extensions](#specifying-valid-file-extensions)
-* [Ignoring Files and Folders](#ignoring-files-and-folders)
-* [Ignoring Parts of a File](#ignoring-parts-of-a-file)
-* [Limiting Results to Specific Sniffs](#limiting-results-to-specific-sniffs)
-* [Filtering Errors and Warnings Based on Severity](#filtering-errors-and-warnings-based-on-severity)
-* [Replacing Tabs with Spaces](#replacing-tabs-with-spaces)
-* [Specifying an Encoding](#specifying-an-encoding)
-* [Using a Bootstrap File](#using-a-bootstrap-file)
-* [Using a Default Configuration File](#using-a-default-configuration-file)
-* [Specifying php.ini Settings](#specifying-phpini-settings)
-* [Setting Configuration Options](#setting-configuration-options)
-* [Deleting Configuration Options](#deleting-configuration-options)
-* [Viewing Configuration Options](#viewing-configuration-options)
-* [Printing Verbose Tokeniser Output](#printing-verbose-tokeniser-output)
-    * [The Scope Map](#the-scope-map)
-    * [The Level Map](#the-level-map)
-* [Printing Verbose Token Processing Output](#printing-verbose-token-processing-output)
-* [Quieting Output](#quieting-output)
-* [Understanding the Exit Codes](#understanding-the-exit-codes)
+<!-- START doctoc -->
+<!-- END doctoc -->
 
 ***
 
diff --git a/wiki/Coding-Standard-Tutorial.md b/wiki/Coding-Standard-Tutorial.md
@@ -2,6 +2,13 @@ In this tutorial, we will create a new coding standard with a single sniff. Our
 
 Sniffs need to follow [strict directory layout and naming conventions](https://github.com/PHPCSStandards/PHP_CodeSniffer/wiki/About-Standards-for-PHP_CodeSniffer#naming-conventions).
 
+## Table of contents
+
+<!-- START doctoc -->
+<!-- END doctoc -->
+
+***
+
 ## Creating the Coding Standard Directory
 
 All sniffs in PHP_CodeSniffer must belong to a coding standard. A coding standard is a directory with a specific sub-directory structure and a `ruleset.xml` file, so creating a standard is straight-forward.
diff --git a/wiki/Configuration-Options.md b/wiki/Configuration-Options.md
@@ -1,27 +1,7 @@
 ## Table of contents
 
-* [Setting the default coding standard](#setting-the-default-coding-standard)
-* [Setting the default report format](#setting-the-default-report-format)
-* [Hiding warnings by default](#hiding-warnings-by-default)
-* [Showing progress by default](#showing-progress-by-default)
-* [Using colors in output by default](#using-colors-in-output-by-default)
-* [Changing the default severity levels](#changing-the-default-severity-levels)
-* [Setting the default report width](#setting-the-default-report-width)
-* [Setting the default encoding](#setting-the-default-encoding)
-* [Setting the default tab width](#setting-the-default-tab-width)
-* [Setting the installed standard paths](#setting-the-installed-standard-paths)
-* [Setting the PHP version](#setting-the-php-version)
-* [Ignoring errors when generating the exit code](#ignoring-errors-when-generating-the-exit-code)
-* [Ignoring warnings when generating the exit code](#ignoring-warnings-when-generating-the-exit-code)
-* [Ignoring non-auto-fixable issues when generating the exit code (PHP_CodeSniffer >= 4.0.0)](#ignoring-non-auto-fixable-issues-when-generating-the-exit-code-php_codesniffer--400)
-* Setting tool paths
-    * [CSSLint](#setting-the-path-to-csslint)
-    * [Google Closure Linter](#setting-the-path-to-the-google-closure-linter)
-    * [PHP](#setting-the-path-to-php)
-    * [JSHint](#setting-the-path-to-jshint)
-    * [JSLint](#setting-the-path-to-jslint)
-    * [JavaScript Lint](#setting-the-path-to-javascript-lint)
-    * [Zend Code Analyzer](#setting-the-path-to-the-zend-code-analyzer)
+<!-- START doctoc -->
+<!-- END doctoc -->
 
 ***
 
diff --git a/wiki/Customisable-Sniff-Properties.md b/wiki/Customisable-Sniff-Properties.md
@@ -4,70 +4,8 @@ For more information about changing sniff behaviour by customising your ruleset,
 
 ## Table of contents
 
-* [Generic Sniffs](#generic-sniffs)
-    * [Generic.Arrays.ArrayIndent](#genericarraysarrayindent)
-    * [Generic.CodeAnalysis.UnusedFunctionParameter](#genericcodeanalysisunusedfunctionparameter)
-    * [Generic.ControlStructures.InlineControlStructure](#genericcontrolstructuresinlinecontrolstructure)
-    * [Generic.Debug.ClosureLinter](#genericdebugclosurelinter)
-    * [Generic.Debug.ESLint](#genericdebugeslint)
-    * [Generic.Files.LineEndings](#genericfileslineendings)
-    * [Generic.Files.LineLength](#genericfileslinelength)
-    * [Generic.Formatting.MultipleStatementAlignment](#genericformattingmultiplestatementalignment)
-    * [Generic.Formatting.SpaceAfterCast](#genericformattingspaceaftercast)
-    * [Generic.Formatting.SpaceAfterNot](#genericformattingspaceafternot)
-    * [Generic.Functions.OpeningFunctionBraceBsdAllman](#genericfunctionsopeningfunctionbracebsdallman)
-    * [Generic.Functions.OpeningFunctionBraceKernighanRitchie](#genericfunctionsopeningfunctionbracekernighanritchie)
-    * [Generic.Metrics.CyclomaticComplexity](#genericmetricscyclomaticcomplexity)
-    * [Generic.Metrics.NestingLevel](#genericmetricsnestinglevel)
-    * [Generic.NamingConventions.CamelCapsFunctionName](#genericnamingconventionscamelcapsfunctionname)
-    * [Generic.PHP.ForbiddenFunctions](#genericphpforbiddenfunctions)
-    * [Generic.PHP.NoSilencedErrors](#genericphpnosilencederrors)
-    * [Generic.Strings.UnnecessaryStringConcat](#genericstringsunnecessarystringconcat)
-    * [Generic.WhiteSpace.ArbitraryParenthesesSpacing](#genericwhitespacearbitraryparenthesesspacing)
-    * [Generic.WhiteSpace.ScopeIndent](#genericwhitespacescopeindent)
-    * [Generic.WhiteSpace.SpreadOperatorSpacingAfter](#genericwhitespacespreadoperatorspacingafter)
-* [PEAR Sniffs](#pear-sniffs)
-    * [PEAR.Commenting.FunctionComment](#pearcommentingfunctioncomment)
-    * [PEAR.ControlStructures.ControlSignature](#pearcontrolstructurescontrolsignature)
-    * [PEAR.ControlStructures.MultiLineCondition](#pearcontrolstructuresmultilinecondition)
-    * [PEAR.Formatting.MultiLineAssignment](#pearformattingmultilineassignment)
-    * [PEAR.Functions.FunctionCallSignature](#pearfunctionsfunctioncallsignature)
-    * [PEAR.Functions.FunctionDeclaration](#pearfunctionsfunctiondeclaration)
-    * [PEAR.WhiteSpace.ObjectOperatorIndent](#pearwhitespaceobjectoperatorindent)
-    * [PEAR.WhiteSpace.ScopeClosingBrace](#pearwhitespacescopeclosingbrace)
-    * [PEAR.WhiteSpace.ScopeIndent](#pearwhitespacescopeindent)
-* [PSR2 Sniffs](#psr2-sniffs)
-    * [PSR2.Classes.ClassDeclaration](#psr2classesclassdeclaration)
-    * [PSR2.ControlStructures.ControlStructureSpacing](#psr2controlstructurescontrolstructurespacing)
-    * [PSR2.ControlStructures.SwitchDeclaration](#psr2controlstructuresswitchdeclaration)
-    * [PSR2.Methods.FunctionCallSignature](#psr2methodsfunctioncallsignature)
-* [PSR12 Sniffs](#psr12-sniffs)
-    * [PSR12.Classes.AnonClassDeclaration](#psr12classesanonclassdeclaration)
-    * [PSR12.ControlStructures.BooleanOperatorPlacement](#psr12controlstructuresbooleanoperatorplacement)
-    * [PSR12.ControlStructures.ControlStructureSpacing](#psr12controlstructurescontrolstructurespacing)
-    * [PSR12.Namespaces.CompoundNamespaceDepth](#psr12namespacescompoundnamespacedepth)
-    * [PSR12.Operators.OperatorSpacing](#psr12operatorsoperatorspacing)
-* [Squiz Sniffs](#squiz-sniffs)
-    * [Squiz.Classes.ClassDeclaration](#squizclassesclassdeclaration)
-    * [Squiz.Commenting.FunctionComment](#squizcommentingfunctioncomment)
-    * [Squiz.Commenting.LongConditionClosingComment](#squizcommentinglongconditionclosingcomment)
-    * [Squiz.ControlStructures.ControlSignature](#squizcontrolstructurescontrolsignature)
-    * [Squiz.ControlStructures.ForEachLoopDeclaration](#squizcontrolstructuresforeachloopdeclaration)
-    * [Squiz.ControlStructures.ForLoopDeclaration](#squizcontrolstructuresforloopdeclaration)
-    * [Squiz.ControlStructures.SwitchDeclaration](#squizcontrolstructuresswitchdeclaration)
-    * [Squiz.CSS.ForbiddenStyles](#squizcssforbiddenstyles)
-    * [Squiz.CSS.Indentation](#squizcssindentation)
-    * [Squiz.Functions.FunctionDeclaration](#squizfunctionsfunctiondeclaration)
-    * [Squiz.Functions.FunctionDeclarationArgumentSpacing](#squizfunctionsfunctiondeclarationargumentspacing)
-    * [Squiz.PHP.CommentedOutCode](#squizphpcommentedoutcode)
-    * [Squiz.PHP.DiscouragedFunctions](#squizphpdiscouragedfunctions)
-    * [Squiz.PHP.ForbiddenFunctions](#squizphpforbiddenfunctions)
-    * [Squiz.Strings.ConcatenationSpacing](#squizstringsconcatenationspacing)
-    * [Squiz.WhiteSpace.FunctionSpacing](#squizwhitespacefunctionspacing)
-    * [Squiz.WhiteSpace.MemberVarSpacing](#squizwhitespacemembervarspacing)
-    * [Squiz.WhiteSpace.ObjectOperatorSpacing](#squizwhitespaceobjectoperatorspacing)
-    * [Squiz.WhiteSpace.OperatorSpacing](#squizwhitespaceoperatorspacing)
-    * [Squiz.WhiteSpace.SuperfluousWhitespace](#squizwhitespacesuperfluouswhitespace)
+<!-- START doctoc -->
+<!-- END doctoc -->
 
 ***
 
diff --git a/wiki/FAQ.md b/wiki/FAQ.md
@@ -1,11 +1,7 @@
 ## Table of contents
 
-* [Does PHP_CodeSniffer perform any code coverage or unit testing?](#does-php_codesniffer-perform-any-code-coverage-or-unit-testing)
-* [My code is fine! Why do I need PHP_CodeSniffer?](#my-code-is-fine-why-do-i-need-php_codesniffer)
-* [Does PHP_CodeSniffer parse my code to ensure it will execute?](#does-php_codesniffer-parse-my-code-to-ensure-it-will-execute)
-* [I don't agree with your coding standards! Can I make PHP_CodeSniffer enforce my own?](#i-dont-agree-with-your-coding-standards-can-i-make-php_codesniffer-enforce-my-own)
-* [How come PHP_CodeSniffer reported errors, I fixed them, now I get even more?](#how-come-php_codesniffer-reported-errors-i-fixed-them-now-i-get-even-more)
-* [What does PHP_CodeSniffer use to tokenize my code?](#what-does-php_codesniffer-use-to-tokenize-my-code)
+<!-- START doctoc -->
+<!-- END doctoc -->
 
 ***
 
diff --git a/wiki/Fixing-Errors-Automatically.md b/wiki/Fixing-Errors-Automatically.md
@@ -1,8 +1,7 @@
 ## Table of contents
 
-* [About Automatic Fixing](#about-automatic-fixing)
-* [Using the PHP Code Beautifier and Fixer](#using-the-php-code-beautifier-and-fixer)
-* [Viewing Debug Information](#viewing-debug-information)
+<!-- START doctoc -->
+<!-- END doctoc -->
 
 ***
 
diff --git a/wiki/Usage.md b/wiki/Usage.md
@@ -1,12 +1,7 @@
 ## Table of contents
 
-* [Getting Help from the Command Line](#getting-help-from-the-command-line)
-* [Checking Files and Folders](#checking-files-and-folders)
-* [Printing a Summary Report](#printing-a-summary-report)
-* [Printing Progress Information](#printing-progress-information)
-* [Specifying a Coding Standard](#specifying-a-coding-standard)
-* [Printing a List of Installed Coding Standards](#printing-a-list-of-installed-coding-standards)
-* [Listing Sniffs Inside a Coding Standard](#listing-sniffs-inside-a-coding-standard)
+<!-- START doctoc -->
+<!-- END doctoc -->
 
 ***
 
diff --git a/wiki/Version-3.0-Upgrade-Guide.md b/wiki/Version-3.0-Upgrade-Guide.md
@@ -7,20 +7,8 @@ PHP_CodeSniffer version 3 contains a large number of core changes and breaks bac
 
 ## Table of contents
 
-* [Upgrading Custom Sniffs](#upgrading-custom-sniffs)
-    * [Extending Other Sniffs](#extending-other-sniffs)
-    * [Extending the Included Abstract Sniffs](#extending-the-included-abstract-sniffs)
-        * [AbstractVariableSniff](#abstractvariablesniff)
-        * [AbstractPatternSniff](#abstractpatternsniff)
-        * [AbstractScopeSniff](#abstractscopesniff)
-    * [New Class Names](#new-class-names)
-        * [PHP_CodeSniffer_File](#php_codesniffer_file)
-        * [PHP_CodeSniffer_Tokens](#php_codesniffer_tokens)
-        * [PHP_CodeSniffer](#php_codesniffer)
-* [Upgrading Unit Tests](#upgrading-unit-tests)
-    * [Setting CLI Values](#setting-cli-values)
-* [Upgrading Custom Reports](#upgrading-custom-reports)
-    * [Supporting Concurrency](#supporting-concurrency)
+<!-- START doctoc -->
+<!-- END doctoc -->
 
 ***
 
diff --git a/wiki/Version-4.0-Developer-Upgrade-Guide.md b/wiki/Version-4.0-Developer-Upgrade-Guide.md
@@ -14,38 +14,10 @@ There is a separate [[Upgrade Guide for Ruleset Maintainers and End-Users|Versio
 
 ## Table of contents
 
-* [Should I upgrade ?](#should-i-upgrade-)
-    * [Upgrade strategies](#upgrade-strategies)
-* [Upgrading the ruleset.xml file](#upgrading-the-rulesetxml-file)
-* [Upgrading Standards](#upgrading-standards)
-    * [Support for external standards named "Internal" has been removed](#support-for-external-standards-named-internal-has-been-removed)
-* [Upgrading Custom Sniffs](#upgrading-custom-sniffs)
-    * [Sniffs need to comply with the naming conventions](#sniffs-need-to-comply-with-the-naming-conventions)
-    * [Sniffs must implement the `PHP_CodeSniffer\Sniffs\Sniff` interface](#sniffs-must-implement-the-php_codesniffersniffssniff-interface)
-    * [Support for JS/CSS has been removed](#support-for-jscss-has-been-removed)
-    * [Property type casting has been made more consistent](#property-type-casting-has-been-made-more-consistent)
-    * [Changed Methods](#changed-methods)
-        * [File::getDeclarationName()](#filegetdeclarationname)
-        * [File::getMemberProperties()](#filegetmemberproperties)
-        * [Config::setConfigData() is no longer static](#configsetconfigdata-is-no-longer-static)
-    * [Tokens class changes](#tokens-class-changes)
-        * [Token arrays are now class constants](#token-arrays-are-now-class-constants)
-        * [Removed Tokens](#removed-tokens)
-    * [Tokenizer Changes](#tokenizer-changes)
-        * [T_USE (for closures), T_ISSET, T_UNSET, T_EMPTY, T_EVAL, T_EXIT are parenthesis owners](#t_use-for-closures-t_isset-t_unset-t_empty-t_eval-t_exit-are-parenthesis-owners)
-        * [Namespaced Names](#namespaced-names)
-        * [T_STATIC](#t_static)
-        * [T_OPEN_TAG](#t_open_tag)
-        * [`goto`](#goto)
-        * [Other Tokenizer Changes](#other-tokenizer-changes)
-    * [Changes to abstract sniffs](#changes-to-abstract-sniffs)
-    * [Changes to PHPCS native sniffs](#changes-to-phpcs-native-sniffs)
-        * [Various sniffs listen to fewer tokens](#various-sniffs-listen-to-fewer-tokens)
-        * [PHP_CodeSniffer\Standards\Squiz\Sniffs\Classes\SelfMemberReferenceSniff](#php_codesnifferstandardssquizsniffsclassesselfmemberreferencesniff)
-* [Miscellaneous other changes which may affect code extending PHP_CodeSniffer](#miscellaneous-other-changes-which-may-affect-code-extending-php_codesniffer)
-* [Unit Tests](#unit-tests)
-    * [For standards using their own test framework](#for-standards-using-their-own-test-framework)
-    * [For standards using the PHPCS native test framework](#for-standards-using-the-phpcs-native-test-framework)
+<!-- START doctoc -->
+<!-- END doctoc -->
+
+***
 
 ## Should I upgrade ?
 
@@ -124,7 +96,7 @@ Support for the JS/CSS tokenizers has been removed. To cause the least amount of
 
 This has been implemented in this way to allow external standards to be cross-version compatible with PHPCS 3.x as well as 4.x for a while and to not force external standards to release a new major release to support PHPCS 4.0 (due to sniffs needing to be removed).
 
-#### Upgrading
+**Upgrading**
 
 Search for sniffs which specify the `public $supportedTokenizers` property to find sniffs which may need updating.
 
@@ -146,7 +118,7 @@ Type casting for sniff property values set from within a ruleset has been made m
 * `null` will now be set to an actual `null` value. Previously, the sniff property would have been set to string `'null'`.
 * Array element values will now also get the type casting treatment. Previously, array values would always be strings.
 
-#### Upgrading
+**Upgrading**
 
 Search for sniff which have `public` properties which can be changed from within a ruleset.
 
@@ -434,7 +406,7 @@ The `AbstractPatternSniff::__construct()` method no longer takes any arguments.
 Since PHPCS 1.4.0, the  AbstractPatternSniff sets the `ignoreComments` option using a `public` var rather than through the constructor.
 This allows the setting to be overwritten in `ruleset.xml` files.
 
-#### Upgrading
+**Upgrading**
 
 * Search for sniffs which extend the `AbstractPatternSniff`.
 * If the sniff calls the `parent::__construct()` method with an argument, remove the argument.
@@ -561,7 +533,7 @@ The `protected` `getDeclarationNameWithNamespace()` and `getNamespaceOfScope()`
 
 The Ruleset class now respects sniff selection via `--sniffs=...`, even when in a test context.
 
-#### Upgrading
+**Upgrading**
 
 If your own test framework contained work-arounds to get round the previous restriction, it should now be safe to remove those work-arounds and to use the `--sniffs=...` argument when initiating the `Config` class.
 
@@ -611,7 +583,7 @@ If an external standard uses its own test framework, this section can be skipped
 For compatibility with the PHP_CodeSniffer native test framework, the directory layout conventions and class naming conventions for tests have to be strictly followed and external standards which want to use the PHPCS native test framework need to be registered in the PHP_CodeSniffer `CodeSniffer.conf` file.
 This is not really any different from before, just even more important now.
 
-#### Upgrading
+**Upgrading**
 
 In practice this means the following for most test suites for external standards which extend the PHP_CodeSniffer native test suite:
 1. In `composer.json`: update the PHPUnit version requirements.
diff --git a/wiki/Version-4.0-User-Upgrade-Guide.md b/wiki/Version-4.0-User-Upgrade-Guide.md
