Merge pull request #3384 from Blargian/custom_rule_images

add custom rule for disallowing markdown image syntax

Author: Blargian

docusaurus.config.js

@@ -98,8 +98,8 @@ const config = {
 					editCurrentVersion: true,
 					breadcrumbs: true,
 					editUrl: ({ docPath }) => {
-						if (docPath === 'index.md') return false
-
+						if (docPath === 'index.md')
+							return false
 						if (
 							docPath.includes('development') ||
 							docPath.includes('engines') ||

scripts/.markdownlint-cli2.yaml

@@ -8,7 +8,7 @@ config:
   MD040:                  false  # Fenced code blocks should have a language specified
   links-url-type:         false  # Disallow relative links to a .md or .mdx file
   custom-anchor-headings: true  # Headings must have a custom anchor which is unique per page eg. # A Heading {#a-heading}
-
+  no-markdown-image-tags: false
   # Keep this item last due to length
   proper-names:                     # MD044
     code_blocks: false
@@ -27,7 +27,7 @@ ignores:
   - "docs/cloud/manage/api"
 customRules:
   # add custom rules here
-  - "./markdownlint/rules/links_url_type.js"
-  - "./markdownlint/rules/headings_have_custom_anchors.js"
+  - "./markdownlint/custom_rules/links_url_type.js"
+  - "./markdownlint/custom_rules/headings_have_custom_anchors.js"
 
 

scripts/markdownlint/custom_rules/README.md

@@ -0,0 +1,72 @@
+# Custom Rules
+
+Add custom rules to this directory and call them in `scripts/.markdownlint-cli2.yaml` here:
+
+```yaml
+customRules:
+ # add custom rules here
+```
+
+## links_url_type
+
+This custom rule is used to check that we have consistent types of linking.
+We want to use URL type links (by slug) as relative links don't work with
+translations.
+
+Examples of valid links: 
+
+```markdown
+[valid link](/docs/interfaces/formats)
+```
+
+Examples of invalid links:
+
+```markdown
+[invalid link](../../docs/interfaces/formats.md)
+```
+
+```markdown
+[invalid link](../../docs/interfaces)
+```
+
+## headings_have_custom_anchors
+
+This custom rule is used to check that every heading has a custom anchor tag.
+This is necessary for our LLM translation system to ensure that linking works.
+
+Examples of valid headings:
+
+```markdown
+## An H2 heading {#an-h2-heading}
+
+### An H3 heading {#an-h3-heading}
+```
+
+Examples of invalid headings:
+
+```markdown
+## An H2 heading
+
+### An H3 heading
+```
+
+## no_markdown_image_tags
+
+Our documentation uses an opinionated guideline on images. We disallow pure
+markdown image declarations using the `![]()` syntax and prefer to use a
+specific image component instead. This rule checks that markdown images are not
+used.
+
+Example of a valid usage:
+
+```markdown
+import image from '@site/static/images/image.png'
+
+<img src={image} alt="Description"/>
+```
+
+Example of an invalid usage:
+
+```markdown
+![An image](/path/to/an/image.png)
+```

scripts/markdownlint/rules/headings_have_custom_anchors.js renamed to scripts/markdownlint/custom_rules/headings_have_custom_anchors.js

@@ -0,0 +1,25 @@
+const { forEachLine, getLineMetadata, isBlankLine } = require(`markdownlint-rule-helpers`);
+const {filterTokens} = require('./utility_functions.js');
+
+// A custom rule to disallow markdown image tags like ![text](url)
+module.exports = {
+    names: ['no-markdown-image-tags'],
+    tags: ["images"],
+    description: 'Disallows markdown image tags. Prefer img tag instead',
+    function: (params, onError) => {
+        filterTokens(params, "inline", (token) => {
+            const children = token.children ?? [];
+            for (const child of children) {
+                const { type, lineNumber, content } = child;
+
+                if (type === "image") {
+                    onError({
+                        lineNumber,
+                        detail: `Markdown image tag found: ![${content}](${child.attrs.find(attr => attr[0] === 'src')[1]})`,
+                    });
+                }
+            }
+        });
+    },
+};
+