Merge pull request #2716 from kiwicom/docs/linting

feat(docs): add linting

.eslintrc.js

@@ -190,6 +190,46 @@ module.exports = {
         "@typescript-eslint/prefer-readonly-parameter-types": "off",
       },
     },
+    {
+      files: "*.mdx",
+      extends: ["plugin:mdx/recommended"],
+      rules: {
+        "react/jsx-filename-extension": ["error", { extensions: [".mdx"] }],
+        "mdx/no-unescaped-entities": "OFF",
+        "mdx/remark": "error",
+        "import/extensions": [
+          "error",
+          "ignorePackages",
+          {
+            tsx: "never",
+          },
+        ],
+      },
+      settings: {
+        "import/resolver": {
+          node: {
+            extensions: [".tsx"],
+          },
+        },
+      },
+      globals: {
+        // Ignore components added as shortcodes so they don't get marked as undefined
+        // TODO: remove the components that aren't shortcodes, just haven't been added yet
+        Callout: false,
+        ComponentStatus: false,
+        Do: false,
+        Dont: false,
+        FancyLink: false,
+        FigmaFile: false,
+        GitHubContributors: false,
+        Guidelines: false,
+        GuidelinesSideBySide: false,
+        IconsDownloadList: false,
+        Palette: false,
+        ReactExample: false,
+        SocialLinks: false,
+      },
+    },
     // some ESLint rules fail in certain cases, so we're disabling them
     {
       files: ["packages/orbit-components/src/utils/**/*"],

.github/contribution/README.md

@@ -7,6 +7,7 @@
   - [Technologies we use](#technologies-we-use)
   - [Starting with development](#starting-with-development)
   - [Testing](#testing)
+- [Contributing to the docs](./docs.md)
 - [Adding a new icon](#adding-a-new-icon)
 - [Props naming convention](#props-naming-convention)
 - [Component design](#component-design)
@@ -67,6 +68,10 @@ If you need to update tests because of some changes in the code, you can do it b
 
 We are still working on this, we will add documentation as soon as possible.
 
+## Contributing to the docs
+
+See our full guide to [contributing to our docs](./docs.md)
+
 ## Adding a new icon
 
 It's easy to update or add a new icon because SVGs are automatically converted to React components. See [this documentation](./icons.md) for more information.

.github/contribution/docs.md

@@ -0,0 +1,114 @@
+# Contributing to the docs
+
+Thank you for your interest in contributing to the Orbit docs.
+It's efforts like yours that help keep our docs useful.
+
+## Table of Contents
+
+- [Location](#location)
+- [Running the docs locally](#running-the-docs-locally)
+- [Code style](#code-style)
+- [Prose style](#prose-style)
+
+## Location
+
+Our docs live mostly in two places.
+
+Basic details (props tables and such) for each component
+live in ReadMe files next to the component
+([example button ReadMe](https://github.com/kiwicom/orbit/blob/master/packages/orbit-components/src/Button/README.md)).
+
+More general guidelines and anything more complex lives in the [docs folder](../../docs),
+mostly in MDX files in the [documentation folder](../../docs/src/documentation).
+The structure of that folder matches the structure on [our built docs site](https://orbit.kiwi).
+
+## Running the docs locally
+
+Our docs site is based on [Gatsby](https://www.gatsbyjs.com/docs/).
+
+To run the site locally, start by cloning this repository.
+
+```shell
+git clone git@github.com:kiwicom/orbit.git
+```
+
+Navigate to the created directory.
+
+```shell
+cd orbit
+```
+
+Install all the necessary packages:
+
+```shell
+yarn
+```
+
+And start the site.
+
+```shell
+yarn dev:docs
+```
+
+Your site is now running at `http://localhost:8000`.
+
+Now you can make a change to a file in `docs/src/` (such as the docs in `docs/src/documentation/`)
+and your site updates automatically.
+
+## Code style
+
+To keep the files used to build our docs clear, we enforce standard Markdown code styling.
+
+We use [ESLint](https://eslint.org/) to enforce the style for our MDX files
+(just as we do for our JavaScript and TypeScript files).
+The specific rules are part of an extension for `eslint-plugin-mdx`,
+which you can find in [our ESLint settings](../../.eslintrc.js)
+(look for the rules that extend `plugin:mdx/recommended`).
+
+To fix any problems that can be fixed automatically,
+you can use an ESLint plugin for your IDE
+or run `yarn eslint:docs` from a terminal.
+
+### Line length
+
+In addition to the automatic fixes,
+we also prefer it when lines are no longer than 80 characters.
+This helps ensure the code is readable even in narrow spaces.
+
+But we don't enforce a strict limit to line length.
+If we did, automatic tools would rearrange lines at any change.
+Then reviews would be more difficult:
+`git diff` would show changes based on formatting rather than meaning.
+
+So we try to break lines at semantic breaks.
+This means having new sentences on new lines.
+This should help keep the differences for review about semantics,
+and not formatting.
+
+## Prose style
+
+In addition to the linting for code style in our docs,
+we also lint to ensure the docs follow our [style guide](https://orbit.kiwi/content/voice-tone/)
+as much as possible.
+
+For this, we use [Vale](https://docs.errata.ai/vale/about).
+Our specifics can be found in the [styles directory](../styles),
+with rules in the `Kiwi` folder and accepted spellings in [accept.txt](../styles/Vocab/Kiwi/accept.txt).
+
+To check your prose yourself, [install Vale](https://docs.errata.ai/vale/install).
+Or you can create a pull request
+and the Vale GitHub Action adds comments pointing out places that could be improved.
+
+The rules aren't perfect at detecting problems,
+so feel free to ignore any suggestions that seem wrong.
+
+## Checking links
+
+It's important for working documentation to have working links.
+
+To achieve this, after building the site, we check all built HTML for working links.
+Any broken link prevents a pull request from being merged.
+
+To check for yourself,
+run `yarn check-links` from a terminal at the root of this repository.
+Note that you need to have built the site first (run `yarn orbit-kiwi build`).

.github/styles/Kiwi/AMPM.yml

@@ -0,0 +1,9 @@
+extends: existence
+message: "Use a 24-hour clock (for example: 23:43)."
+link: 'https://orbit.kiwi/content/grammar-and-mechanics/#currency'
+level: error
+nonword: true
+tokens:
+  - '\d{1,2}[aApP][Mm]'
+  - '\d{1,2} ?[aApP][Mm]'
+  - '\d{1,2} ?[aApP]\.[mM]\.'

.github/styles/Kiwi/Abbreviations.yml

@@ -0,0 +1,64 @@
+extends: conditional
+message: "Spell out '%s', if it's unfamiliar to the audience."
+link: 'https://developers.google.com/style/abbreviations'
+level: suggestion
+ignorecase: false
+# Ensures that the existence of 'first' implies the existence of 'second'.
+first: '\b([A-Z]{3,5})\b'
+second: '(?:\b[a-zA-Z]+ )+\(([A-Z]{3,5})\)'
+# ... with the exception of these:
+exceptions:
+  - API
+  - ASP
+  - CLI
+  - CPU
+  - CSS
+  - CSV
+  - DEBUG
+  - DOM
+  - DPI
+  - FAQ
+  - GCC
+  - GDB
+  - GET
+  - GPU
+  - GTK
+  - GUI
+  - HTML
+  - HTTP
+  - HTTPS
+  - IDE
+  - JAR
+  - JSON
+  - JSX
+  - LESS
+  - LLDB
+  - NET
+  - NOTE
+  - NVDA
+  - OSS
+  - PATH
+  - PDF
+  - PHP
+  - POST
+  - RAM
+  - REPL
+  - RSA
+  - SCM
+  - SCSS
+  - SDK
+  - SQL
+  - SSH
+  - SSL
+  - SVG
+  - TBD
+  - TCP
+  - TODO
+  - URI
+  - URL
+  - USB
+  - UTF
+  - XML
+  - XSS
+  - YAML
+  - ZIP

.github/styles/Kiwi/Britishisms.yml

@@ -0,0 +1,91 @@
+extends: substitution
+message: "Use the American spelling '%s' instead of '%s'."
+link: 'https://orbit.kiwi/content/grammar-and-mechanics/#spelling'
+ignorecase: true
+level: warning
+action:
+  name: replace
+swap:
+  aeroplane: airplane
+  ageing: aging
+  aluminium: aluminum
+  analogue: analog
+  analyse: analyze
+  analysed: analyzed
+  annexe: annex
+  apologise: apologize
+  behaviour: behavior
+  busses: buses
+  centre: center
+  cheque: check
+  civilisation: civilization
+  civilise: civilize
+  colour: color
+  cosy: cozy
+  cypher: cipher
+  dependant: dependent
+  defence: defense
+  dialogue: dialog
+  draught: draft
+  enquiry: inquiry
+  enrol: enroll
+  enrolment: enrollment
+  favourite: favorite
+  fibre: fiber
+  flavour: flavor
+  focussed: focused
+  fuelled: fueled
+  fuelling: fueling
+  fulfil: fulfill
+  grey: gray
+  humour: humor
+  honour: honor
+  initialled: initialed
+  initialling: initialing
+  instil: instill
+  jewellery: jewelry
+  labelling: labeling
+  labelled: labeled
+  labour: labor
+  licence: license
+  likeable: likable
+  litre: liter
+  liveable: livable
+  metre: meter
+  modelling: modeling
+  moustache: mustache
+  neighbour: neighbor
+  normalise: normalize
+  offence: offense
+  organisation: organization
+  organise: organize
+  organised: organized
+  organising: organizing
+  orientated: oriented
+  paralyse: paralyze
+  plough: plow
+  practise: practice
+  pretence: pretense
+  programme: program
+  pyjamas: pajamas
+  rateable: ratable
+  realise: realize
+  realised: realized
+  recognise: recognize
+  recognised: recognized
+  rumour: rumor
+  saleable: salable
+  sceptic: skeptic
+  signalling: signaling
+  sizeable: sizable
+  skilful: skillful
+  speciality: specialty
+  standardise: standardize
+  standardised: standardized
+  theatre: theater
+  travelled: traveled
+  traveller: traveler
+  travelling: traveling
+  unshakeable: unshakable
+  wilful: willful
+  yoghurt: yogurt

.github/styles/Kiwi/CommonErrors.yml

@@ -0,0 +1,12 @@
+extends: substitution
+message: "Use '%s' instead of '%s'."
+link: 'https://orbit.kiwi/content/grammar-and-mechanics/#spelling'
+ignorecase: true
+level: warning
+action:
+  name: replace
+swap:
+  comprise of: comprise
+  comprises of: comprises
+  reason why: reason
+  way how: way

.github/styles/Kiwi/Contractions.yml

@@ -0,0 +1,29 @@
+extends: substitution
+message: "Feel free to use '%s' instead of '%s'."
+link: 'https://orbit.kiwi/content/technical-content/language/#use-contractions'
+level: suggestion
+ignorecase: true
+action:
+  name: replace
+swap:
+  are not: aren't
+  cannot: can't
+  could not: couldn't
+  did not: didn't
+  do not: don't
+  does not: doesn't
+  has not: hasn't
+  have not: haven't
+  is not: isn't
+  it is: it's
+  should not: shouldn't
+  that is: that's
+  they are: they're
+  was not: wasn't
+  we are: we're
+  were not: weren't
+  what is: what's
+  when is: when's
+  where is: where's
+  will not: won't
+  you are: you're