[docs] Fix markdown table alignments (mui#36136)

mnajdova · Feb 15, 2023 · a18006a · a18006a
1 parent 718d377
commit a18006a
Show file tree

Hide file tree

Showing 12 changed files with 62 additions and 26 deletions.
diff --git a/.markdownlint-cli2.cjs b/.markdownlint-cli2.cjs
@@ -1,5 +1,6 @@
 const straightQuotes = require('./packages/markdownlint-rule-mui/straight-quotes');
 const gitDiff = require('./packages/markdownlint-rule-mui/git-diff');
+const tableAlignment = require('./packages/markdownlint-rule-mui/table-alignment');
 
 // https://github.com/DavidAnson/markdownlint#rules--aliases
 module.exports = {
@@ -31,8 +32,9 @@ module.exports = {
     MD052: false, // MD052/reference-links-images. Many false positives in the changelog.
     straightQuotes: true,
     gitDiff: true,
+    tableAlignment: true,
   },
-  customRules: [straightQuotes, gitDiff],
+  customRules: [straightQuotes, gitDiff, tableAlignment],
   ignores: [
     'CHANGELOG.old.md',
     '**/node_modules/**',

diff --git a/SECURITY.md b/SECURITY.md
@@ -5,10 +5,10 @@
 The versions of the project that are currently supported with security updates.
 
 | Version | Supported          |
-| ------- | ------------------ |
-| 5.x     | :white_check_mark: |
-| 4.x     | :white_check_mark: |
-| < 4.0   | :x:                |
+| ------: | :----------------- |
+|     5.x | :white_check_mark: |
+|     4.x | :white_check_mark: |
+|   < 4.0 | :x:                |
 
 ## Reporting a vulnerability
 

diff --git a/docs/data/base/components/form-control/form-control.md b/docs/data/base/components/form-control/form-control.md
@@ -86,7 +86,7 @@ This way, you don't have to implement both in your custom input—Unstyled Form
 `useFormControlUnstyledContext` returns an object with the following fields:
 
 | Name       | Type    | Description                                                                                                                                                                         |
-| ---------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| :--------- | :------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `disabled` | boolean | Represents the value of the FormControlUnstyled's `disabled` prop.                                                                                                                  |
 | `error`    | boolean | Represents the value of the Unstyled Form Control component's `error` prop. Note that it is not calculated automatically (i.e. it's not set when `required: true` and `value: ''`). |
 | `filled`   | boolean | Set to `true` if `value` is not empty.                                                                                                                                              |
@@ -97,7 +97,7 @@ This way, you don't have to implement both in your custom input—Unstyled Form
 The following callbacks are also part of the returned object—they are meant to be used when creating custom inputs:
 
 | Name       | Type                      | Description                                                   |
-| ---------- | ------------------------- | ------------------------------------------------------------- |
+| :--------- | :------------------------ | :------------------------------------------------------------ |
 | `onChange` | React.ChangeEvent => void | Value change handler. Should be forwarded to the inner input. |
 | `onBlur`   | () => void                | Focus change handler. Should be forwarded to the inner input. |
 | `onFocus`  | () => void                | Focus change handler. Should be forwarded to the inner input. |

diff --git a/docs/data/material/discover-more/roadmap/roadmap.md b/docs/data/material/discover-more/roadmap/roadmap.md
@@ -47,7 +47,7 @@ Here are the components we will work on being supported in the MUI ecosystem:
 - ⏳ Planning to build
 
 | Name                       | Product  | Status |
-| :------------------------- | -------- | ------ |
+| :------------------------- | :------- | :----- |
 | Advanced Layout            | MUI X    | ⏳     |
 | Carousel                   | MUI X    | ⏳     |
 | Charts                     | MUI X    | ⏳     |

diff --git a/docs/data/material/experimental-api/css-theme-variables/overview.md b/docs/data/material/experimental-api/css-theme-variables/overview.md
@@ -27,7 +27,7 @@ CSS theme variable support is a new feature in Material UI added in [`v5.6.0`](h
 For server-side applications, there are some trade-offs to consider:
 
 |                                                      | Compare to the default method | Reason                                                                                                       |
-| ---------------------------------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| :--------------------------------------------------- | :---------------------------- | :----------------------------------------------------------------------------------------------------------- |
 | HTML size                                            | Bigger                        | CSS variables are generated for both light and dark mode at build time.                                      |
 | [First Contentful Paint (FCP)](https://web.dev/fcp/) | Larger                        | Since the HTML size is generally bigger, the time to download the HTML before showing the content is longer. |
 | [Time to Interactive (TTI)](https://web.dev/tti/)    | Smaller (for dark mode)       | Stylesheets are not regenerated between light and dark mode, so it takes less time for JavaScript to run.    |

diff --git a/docs/data/system/getting-started/usage/usage.md b/docs/data/system/getting-started/usage/usage.md
@@ -155,11 +155,11 @@ It works with both Emotion and styled-components.
 - Runtime performance takes a hit.
 
   | Benchmark case                    | Code snippet          | Time normalized |
-  | :-------------------------------- | :-------------------- | --------------- |
-  | a. Render 1,000 primitives        | `<div className="…">` | 100ms           |
-  | b. Render 1,000 components        | `<Div>`               | 112ms           |
-  | c. Render 1,000 styled components | `<StyledDiv>`         | 181ms           |
-  | d. Render 1,000 Box               | `<Box sx={…}>`        | 296ms           |
+  | :-------------------------------- | :-------------------- | --------------: |
+  | a. Render 1,000 primitives        | `<div className="…">` |           100ms |
+  | b. Render 1,000 components        | `<Div>`               |           112ms |
+  | c. Render 1,000 styled components | `<StyledDiv>`         |           181ms |
+  | d. Render 1,000 Box               | `<Box sx={…}>`        |           296ms |
 
 <!-- #default-branch-switch -->
 

diff --git a/docs/pages/blog/2019-developer-survey-results.md b/docs/pages/blog/2019-developer-survey-results.md
@@ -184,14 +184,14 @@ above 0 is considered "good", +50 is "Excellent", and above 70 is considered "wo
 Multiple options were allowed.
 
 | Channel(s)                  | Number |
-| --------------------------- | ------ |
-| Search                      | 344    |
-| Word of mouth               | 112    |
-| Search, Word of mouth       | 47     |
-| Search, Social              | 25     |
-| Social                      | 22     |
-| Blog                        | 14     |
-| Search, Word of mouth, Blog | 11     |
+| :-------------------------- | -----: |
+| Search                      |    344 |
+| Word of mouth               |    112 |
+| Search, Word of mouth       |     47 |
+| Search, Social              |     25 |
+| Social                      |     22 |
+| Blog                        |     14 |
+| Search, Word of mouth, Blog |     11 |
 
 <br /><br />
 <img src="/static/blog/2019-survey/6.png" style="display: block; margin: 0 auto;" alt="Bar chart: 74.3% search, 29.6% word of mouth, 8.2% Social, 4.3% blog." />

diff --git a/packages/markdownlint-rule-mui/straight-quotes.js b/packages/markdownlint-rule-mui/straight-quotes.js
@@ -12,7 +12,7 @@ module.exports = {
       if (line.match('[‘’“”]')) {
         onError({
           lineNumber: lineNumber + 1,
-          details: `For line: ${line}`,
+          detail: `For line: ${line}`,
         });
       }
     });

diff --git a/packages/markdownlint-rule-mui/table-alignment.js b/packages/markdownlint-rule-mui/table-alignment.js
@@ -0,0 +1,34 @@
+function attr(attrs) {
+  return (attrs || []).reduce((acc, item) => ({ ...acc, [item[0]]: item[1] }), {});
+}
+
+module.exports = {
+  names: ['tableAlignment'],
+  description: 'Set table alignment.',
+  tags: ['table'],
+  function: (params, onError) => {
+    params.tokens.forEach((token) => {
+      // This is wrong:
+      // | Version | Supported          |
+      // | ------- | ------------------ |
+      //
+      // The second column should be left aligned because it contains text:
+      // | Version | Supported          |
+      // | ------- | :----------------- |
+      //
+      // However, columns that includes numbers should be right aligned:
+      // | Version | Supported          |
+      // | ------: | :----------------- |
+      //
+      // More details: https://ux.stackexchange.com/questions/24066/what-is-the-best-practice-for-data-table-cell-content-alignment
+      //
+      // In this check we expect the style to be 'text-align:right' or equivalent.
+      if (token.type === 'th_open' && attr(token.attrs).style == null) {
+        onError({
+          lineNumber: token.lineNumber,
+          detail: `${params.lines[token.lineNumber - 1]}`,
+        });
+      }
+    });
+  },
+};
diff --git a/packages/typescript-to-proptypes/README.md b/packages/typescript-to-proptypes/README.md
@@ -5,7 +5,7 @@ An API for converting [TypeScript](https://www.npmjs.com/package/typescript) def
 ## Support
 
 | Component type   |                    |
-| ---------------- | ------------------ |
+| :--------------- | :----------------- |
 | Class            | :heavy_check_mark: |
 | Function         | :heavy_check_mark: |
 | Const functions  | :heavy_check_mark: |

diff --git a/test/e2e/README.md b/test/e2e/README.md
@@ -22,7 +22,7 @@ A fixture can be loaded with `await renderFixture(fixturePath)` e.g. `renderFixt
 For development `yarn test:e2e:dev` and `yarn test:e2e:run --watch` in separate terminals is recommended.
 
 | command                | description                                                                                   |
-| ---------------------- | --------------------------------------------------------------------------------------------- |
+| :--------------------- | :-------------------------------------------------------------------------------------------- |
 | `yarn test:e2e`        | Full run                                                                                      |
 | `yarn test:e2e:dev`    | Prepares the fixtures to be able to test in watchmode                                         |
 | `yarn test:e2e:run`    | Runs the tests (requires `yarn test:e2e:dev` or `yarn test:e2e:build`+`yarn test:e2e:server`) |

diff --git a/test/regressions/README.md b/test/regressions/README.md
@@ -48,7 +48,7 @@ A fixture can be loaded with `await renderFixture(fixturePath)` e.g. `renderFixt
 For development `yarn test:regressions:dev` and `yarn test:regressions:run --watch` in separate terminals is recommended.
 
 | command                        | description                                                                                                           |
-| ------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
+| :----------------------------- | :-------------------------------------------------------------------------------------------------------------------- |
 | `yarn test:regressions`        | Full run                                                                                                              |
 | `yarn test:regressions:dev`    | Prepares the fixtures to be able to test in watchmode                                                                 |
 | `yarn test:regressions:run`    | Runs the tests (requires `yarn test:regressions:dev` or `yarn test:regressions:build`+`yarn test:regressions:server`) |