Introduce markdownlinting (primer#345)

* Add markdownlint and markdownlint-github

* Update node version to 14

* Bump markdownlint-github

* Disable rules we don't currently care about

* cleanup

* Split markdownlint command per @jonrohan suggestion

* Split jobs

* fix: MD019/no-multiple-space-atx Multiple spaces after hash on atx style heading

* fix: MD045/no-alt-text Images should have alternate text (alt text)

* fix: MD001/heading-increment/header-increment Heading levels should only increment by one level at a time [Expected: h3; Actual: h4]

* fix: MD040/fenced-code-language Fenced code blocks should have a language specified

* fix: GH002/no-generic-link-text Avoid using generic link text like  or  [For link: here]

* fix: MD042/no-empty-links No empty links

* fix: MD036/no-emphasis-as-heading/no-emphasis-as-header Emphasis used instead of a heading

* fix: MD051/link-fragments Link fragments should be valid

* fix: MD024/no-duplicate-heading/no-duplicate-header Multiple headings with the same content

.github/workflows/ci.yml

@@ -1,7 +1,7 @@
 name: Lint
 on: [push]
 jobs:
-  all:
+  eslint:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@master
@@ -10,5 +10,16 @@ jobs:
           version: 14
       - name: install
         run: yarn
-      - name: lint
+      - name: Lint with ESLint
         run: yarn lint
+  markdownlint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@master
+      - uses: actions/setup-node@master
+        with:
+          version: 14
+      - name: install
+        run: yarn
+      - name: Lint with markdownlint
+        run: yarn markdownlint

.github/workflows/deploy.yml

@@ -17,7 +17,7 @@ jobs:
     # SHA for security hardening. Points at last verified HEAD of main branch.
     uses: primer/.github/.github/workflows/deploy.yml@0cec9b9914f358846163f2428663b58da41028c9
     with:
-      node_version: 12
+      node_version: 14
       install: yarn
       build: yarn build
       output_dir: public

.github/workflows/deploy_preview.yml

@@ -17,7 +17,7 @@ jobs:
     secrets:
       gh_token: ${{ secrets.GITHUB_TOKEN }}
     with:
-      node_version: 12
+      node_version: 14
       install: yarn
       build: yarn build:preview
       output_dir: public

.markdownlint-cli2.cjs

@@ -0,0 +1,19 @@
+const githubMarkdownOpinions = require('@github/markdownlint-github')
+
+const options = githubMarkdownOpinions.init({
+  // Disable rules we don't currently care to enforce pertaining to stylistic things.
+  'line-length': false,
+  'blanks-around-headings': false,
+  'blanks-around-lists': false,
+  'no-trailing-spaces': false,
+  'no-multiple-blanks': false,
+  'no-trailing-punctuation': false,
+  'single-trailing-newline': false,
+  'ul-indent': false,
+  'no-hard-tabs': false
+})
+
+module.exports = {
+  config: options,
+  customRules: ["@github/markdownlint-github"],
+}

content/components/component-documentation-guidelines/component-documentation-guidelines.md

@@ -19,7 +19,7 @@ When documenting components, consider the core elements needed to convey its mai
 
 See our full [documentation guidelines here](https://primer.style/contribute/documentation/). 
 
-#### Types of components 
+### Types of components 
 - **Regular**: Standard components used to build Primer UI. See [ActionList](https://primer.style/design/components/action-list).
 - **Internal**: Components used by other components that do not exist on their own. See [Overlay](https://primer.style/react/Overlay).
 - **Behavioral**: Components with no real anatomy or structure, rather behaviors. See [Truncate](https://primer.style/react/Truncate).

content/components/data-table.mdx

@@ -164,7 +164,7 @@ These factors make it difficult to recommend an “ideal” page size for all us
 
 #### Communicate when the table has no data to show
 
-Show a [Blankslate]() component in place of the table
+Show a `Blankslate` component in place of the table
 
 #### Consider small screens
 

content/foundations/typography.mdx

@@ -29,19 +29,19 @@ We utilize system fonts at GitHub, which allow for optimized performance. This d
 
 **System Fonts**—default GitHub font-stack with ample fallbacks alongside emoji support
 
-```
+```css
 font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";
 ```
 
 **Monospace**—used within GitHub product to display metadata or captions, and used in marketing contexts as subheaders
 
-```
+```css
 $mono-font: "SFMono-Regular", Consolas, "Liberation Mono", Menlo, Courier, monospace !default;
 ```
 
 **Display face**—the font stack that implements Inter UI
 
-```
+```css
 font-family: InterUI, -apple-system, BlinkMacSystemFont, "Helvetica Neue", "Segoe UI", Oxygen, Ubuntu, Cantarell, "Open Sans", sans-serif;
 ```
 

content/ui-patterns/button-usage.mdx

@@ -116,13 +116,13 @@ Buttons that only use an icon should still have a label that is invisible to sig
 
 Counters can be added in appropriate scenarios to provide context. For example, showing social proof by displaying the number of people watching a repo.
 
-#### Counter inside button
+### Counter inside button
 
 A count can be displayed inside of a button using a [CounterLabel](https://primer.style/react/CounterLabel).
 
 ![button with count inside](https://user-images.githubusercontent.com/2313998/129626580-465111c8-9237-4e33-af42-b2e830ea9cc3.png)
 
-#### Counter attached to a button
+### Counter attached to a button
 
 A count can be displayed as a separate element that is attached to a button. Only display a count as separate element that is attached to a button when the button uses the "small" size variant and the button type is "Default" or "Outline".
 

content/ui-patterns/empty-states.mdx

@@ -29,7 +29,7 @@ Blankslates can and are encouraged to use one primary action. This button should
 
 ### Secondary action
 
-Secondary actions are optional and are represented by a text link located below the primary action button. A secondary action is used to direct a user to additional content about the feature. This might look like "[Learn more about X](#)" or "[Check out the guide on X](#)" or simply "[Learn more](#)".
+Secondary actions are optional and are represented by a text link located below the primary action button. A secondary action is used to direct a user to additional content about the feature. This might look like `Learn more about X` or "`Check out the guide on X`.
 
 ### Border
 

content/ui-patterns/feature-onboarding.mdx

@@ -133,7 +133,7 @@ Treat feature onboarding as a story or a journey with a beginning, middle, and e
 
 A teaching bubble is a [popover](https://primer.style/css/components/popover) that calls attention to a feature in a specific part of the page. Generally, teaching bubbles should be used to educate the user and enrich the task at hand.
 
-### Usage guidelines
+### Usage guidelines for teaching bubble
 
 Teaching bubble Figma [sticker sheet](https://www.figma.com/file/Y2xJLFBrU7yyiDLlEkQXcF/Primer-Interfaces?node-id=2%3A1295&t=2xX6FwLSJ0Cq9Qkp-1).
 
@@ -313,7 +313,7 @@ Use inline banners in a page with multiple steps or actions.
 
 Use empty states as an integrated way to onboard users to new features. Read more about [empty states](/ui-patterns/empty-states).
 
-**In-product marketing empty state**
+#### In-product marketing empty state
 
 For special occasions, a first time experience may be more unique than the typical blank state. Take a more branded approach to engage and guide the user through complex experiences. Be aware of how the experience will change once the first-time UI is no longer there.
 

content/ui-patterns/forms.mdx

@@ -35,7 +35,7 @@ A caption may be used to provide additional context about the field to help user
 
 Caption text may be displayed alongside a validation message, or it may be hidden if it only provides redundant information.
 
-Caption text may be used to augment the [label](#label), but should not be redundant with the label or any other parts of the form control. If the caption feels redundant, try removing it.
+Caption text may be used to augment the [label](#label-required), but should not be redundant with the label or any other parts of the form control. If the caption feels redundant, try removing it.
 
 <DoDontContainer>
   <Do>
@@ -104,7 +104,7 @@ For more information about form validation, see the [validation guidelines](#val
 
 ![Text input, open-ended autocomplete text input, plain text input, textarea](https://user-images.githubusercontent.com/2313998/170069913-325a987b-9a75-4e83-826a-bb7ae73d6831.png)
 
-Use an open-ended text field when the field does not have a list of possible values. If the input is able to suggest values, use [autocomplete](#autocomplete) to allow users to pick a value or enter their own.
+Use an open-ended text field when the field does not have a list of possible values. If the input is able to suggest values, use [autocomplete](/components/avatar-pair) to allow users to pick a value or enter their own.
 
 ### A set of selectable options
 

content/ui-patterns/messaging.mdx

@@ -60,7 +60,7 @@ Toasts should be brief and not bog down the experience with superfluous copy. If
 
 ### Accessibility
 
-Toasts are non-modal components and should contain `role=log`, which implies the element has `aria-live="polite"`. This notifies the user of the toast via Assistance Technologies without having to change focus to the toast. You can read more about `role=log` [here](https://www.w3.org/WAI/WCAG21/Techniques/aria/ARIA23).
+Toasts are non-modal components and should contain `role=log`, which implies the element has `aria-live="polite"`. This notifies the user of the toast via Assistance Technologies without having to change focus to the toast. You can read more about `role=log` at [W3: Using `role=log` to identify sequential information updates](https://www.w3.org/WAI/WCAG21/Techniques/aria/ARIA23).
 
 Toasts are generally informative and should not receive focus when they appear. For that reason, we suggest you **avoid using interactive elements** in the component (aside from a dismiss action). Keep in mind that, even without an explicit dismiss action, the user can always hit `esc` to dismiss the toast. For more information on how interactive children affect web accessibility, [check out this issue](https://github.com/jackbsteinberg/std-toast/issues/29).
 

docs/content.md

@@ -2,7 +2,7 @@
 
 ## Guidelines
 
-###  Principles
+### Principles
 
 * Accessibility: (Inclusive) consider a11y in design early, list of tools
 * Safety: designing for safety

package.json

@@ -7,7 +7,8 @@
     "build": "gatsby build --prefix-paths",
     "build:preview": "gatsby build",
     "now-build": "yarn build",
-    "lint": "eslint ."
+    "lint": "eslint .",
+    "markdownlint": "markdownlint-cli2 \"**/*.{md,mdx}\" \"!.github\" \"!node_modules\""
   },
   "dependencies": {
     "@github/prettier-config": "^0.0.4",
@@ -25,6 +26,8 @@
     "yarn": "^1.22.18"
   },
   "devDependencies": {
+    "@github/markdownlint-github": "^0.2.1",
+    "markdownlint-cli2": "^0.5.1",
     "path-browserify": "^1.0.1"
   },
   "resolutions": {