MNT Fix linting issues

DOC Document linting documentation

DOC Document how to include filenames for code blocks

.editorconfig

@@ -10,8 +10,5 @@ indent_style = space
 insert_final_newline = true
 trim_trailing_whitespace = true
 
-[*.md]
-trim_trailing_whitespace = false
-
 [composer.json]
-indent_size = 4
+indent_size = 4

.eslintrc.js

@@ -13,12 +13,24 @@ rules.overrides = [
         impliedStrict: true
       }
     },
+    settings: {
+      react: {
+        version: '16'
+      }
+    },
     rules: {
+      // These rules are not appropriate for linting markdown code blocks
       'lines-around-comment': 'off',
       'import/no-unresolved': 'off',
+      'import/extensions': 'off',
+      'react/jsx-no-undef': 'off',
       'no-undef': 'off',
       'no-unused-expressions': 'off',
       'no-unused-vars': 'off',
+      'brace-style': 'off', // it's useful to have comments before the else block
+      // These rules are disabled because they are difficult to adhere to right now
+      'jsx-a11y/label-has-associated-control': 'off',
+      'react/prefer-stateless-function': 'off',
     }
   }
 ];

.github/workflows/ci.yml

@@ -31,7 +31,7 @@ jobs:
         with:
           node-version: ${{ steps.read-nvm.outputs.version }}
 
-      - name: Install yarn and dependencies
+      - name: Install yarn dependencies
         run: |
           npm install --global yarn
           yarn install
@@ -44,7 +44,7 @@ jobs:
 
       - name: Install composer dependencies
         if: ${{ matrix.script == 'lint-php' }}
-        run: composer install --prefer-dist --no-progress --ansi --no-interaction --no-scripts --no-plugins --optimize-autoloader
+        run: composer install --prefer-dist --no-progress --ansi --no-interaction --optimize-autoloader
 
       - name: Run lint
         run: yarn ${{ matrix.script }}

.markdownlint-cli2.mjs

@@ -1,10 +1,13 @@
 
-// const extraRules = require("extraRules");
 import markdownlint from 'markdownlint';
+import enhancedProperNames from 'markdownlint-rule-enhanced-proper-names/src/enhanced-proper-names.js';
 import titleCaseStyle from 'markdownlint-rule-title-case-style';
 import { load } from 'js-yaml';
 
 export default {
-    'customRules': [ titleCaseStyle ],
+    'customRules': [
+        enhancedProperNames,
+        titleCaseStyle,
+    ],
     'config': markdownlint.readConfigSync('./.markdownlint.yml', [ load ]),
 };

.markdownlint.yml

@@ -1,23 +1,6 @@
 # Enable all rules with default settings as a baseline
 default: true
 
-customRules:
-  - 'markdownlint-rule-title-case-style'
-
-# markdownlint-rule-title-case-style: Use sentence-style headings
-title-case-style:
-  case: 'sentence'
-  ignore:
-    - 'GitHub'
-    - 'GraphQL'
-    - 'JavaScript'
-    - 'I'
-    - 'InnoDB'
-    - 'MyISAM'
-    - 'MySQL'
-    - 'RFCs'
-    - 'Silverstripe'
-
 # MD041: Ignore the frontmatter (metadata) title when checking for H1s
 first-line-h1:
   front_matter_title: ''
@@ -46,7 +29,7 @@ ul-style:
 ol-prefix:
   style: 'one'
 
-# MD013: Disable line-length rule (for now)
+# MD013: Disable line-length rule for now as it touches too many lines of doc
 line-length: false
 # line_length: 120
 
@@ -69,7 +52,7 @@ code-block-style:
 
 # MD048: Use backticks for codeblocks
 code-fence-style:
-  style: backtick
+  style: 'backtick'
 
 # MD040: Explicitly only allow some languages for code blocks
 # This helps with consistency (e.g. avoid having both yml and yaml)
@@ -78,27 +61,94 @@ fenced-code-language:
   allowed_languages:
     - 'bash' # use this instead of shell or env
     - 'css'
+    - 'diff'
     - 'graphql'
+    - 'html'
     - 'js'
+    - 'json'
     - 'php'
     - 'scss'
     - 'ss'
+    - 'sql'
     - 'text'
+    - 'xml'
     - 'yml'
 
-# MD044: Enforces capitalisation for specific names
-proper-names:
+# MD044: Disable in favour of the enhanced version which ignores custom anchors for headings
+# markdownlint-rule-enhanced-proper-names: Enforces capitalisation for specific names
+proper-names: off
+enhanced-proper-names:
   code_blocks: false
+  heading_id: false
   names:
+    - 'API'
+    - 'type/api-break' # the GitHub label
+    - 'CI'
     - 'CMS'
+    - '/cms' # e.g. "silverstripe/cms"
+    - '-cms' # e.g. "silverstripe/recipe-cms"
     - 'CSS'
+    - 'GitHub'
+    - 'GraphQL'
+    - '/graphql' # e.g. "silverstripe/graphql"
+    - 'HTTP'
     - 'JavaScript'
     - 'JS'
+    - '.js' # e.g. "Node.js"
+    - 'jQuery'
+    - 'ORM'
+    - 'PHP'
+    - 'php-' # e.g. "php-intl extension"
     - 'SCSS'
     - 'Silverstripe'
+    - 'silverstripe/' # e.g. "silverstripe/framework"
+    - 'silverstripe-' # e.g. "silverstripe-vendormodule"
+    - '@silverstripe.org'
+    - 'TinyMCE'
+    - 'UI'
+    - 'URL'
+    - 'YAML'
+
+# markdownlint-rule-title-case-style: Use sentence-style headings
+title-case-style:
+  case: 'sentence'
+  # commas in the following list are intentional and necessary since the plugin makes no distinction
+  # between words and punctuation
+  ignore:
+    - 'Apache'
+    - 'APIs'
+    - 'Composer'
+    - 'GitHub'
+    - 'GraphQL'
+    - 'Huntr'
+    - 'JavaScript'
+    - 'I'
+    - 'InnoDB'
+    - 'Git'
+    - 'jQuery'
+    - 'jQuery,'
+    - 'Lighttpd'
+    - 'MyISAM'
+    - 'MySQL'
+    - 'Nginx'
+    - 'Nginx,'
+    - 'PHPUnit'
+    - 'RFCs'
+    - 'Silverstripe'
+    - 'TinyMCE'
+    - 'Transifex'
+    - 'URLs'
+    - 'WebP'
 
 # MD033: Allow specific HTML tags
 no-inline-html:
   allowed_elements:
+    # br is necessary for new lines in tables
+    - 'br'
+    # accordians are okay
     - 'details'
     - 'summary'
+    # description lists are okay
+    - 'dl'
+    - 'dd'
+    - 'dt'

composer.json

@@ -21,7 +21,7 @@
         }
     ],
     "require-dev": {
-        "silverstripe/markdown-php-codesniffer": "^1.0",
+        "silverstripe/markdown-php-codesniffer": "^1",
         "slevomat/coding-standard": "^8.14"
     },
     "config": {