Add Markdown linting

docs/.eslintignore

@@ -0,0 +1 @@
+!.*.js

docs/.remarkrc.js

@@ -0,0 +1,38 @@
+/* eslint-disable import/no-commonjs */
+const remarkMode = process.env.REMARK_MODE;
+/**
+ * Linting config.
+ * Check the followin links for the list of all rules:
+ * - https://github.com/remarkjs/remark-lint/tree/master/packages/remark-preset-lint-consistent
+ * - https://github.com/remarkjs/remark-lint/tree/master/packages/remark-preset-lint-recommended
+ * - https://github.com/remarkjs/remark-lint/tree/master/packages/remark-preset-lint-markdown-style-guide
+ **/
+const lintConfig = {
+  plugins: [
+    'frontmatter',
+    'remark-preset-lint-consistent',
+    'remark-preset-lint-recommended',
+    'preset-lint-markdown-style-guide',
+
+    'lint-no-trailing-spaces', // No trailing spaces
+    ['lint-emphasis-marker', '_'], // Italic with _, bold with **
+    ['lint-list-item-indent', 'space'], // Indent list items with one space
+  ],
+};
+const fixConfig = {
+  settings: {
+    emphasis: '_', // Italic with _
+    strong: '*', // Bold with *
+    listItemIndent: 1, // Indent list items with one space
+  },
+  plugins: {
+    frontmatter: true,
+    'reference-links': true,
+    'word-wrap': true,
+  },
+};
+
+const config = remarkMode === 'fix' ? fixConfig : lintConfig;
+
+exports.plugins = config.plugins;
+exports.settings = config.settings;

docs/config.json

@@ -83,7 +83,7 @@
     }
   ],
   "redirects": [
-    { 
+    {
       "from": "documentation/docsearch/introduction/index.html",
       "to": "what-is-docsearch.html"
     },
@@ -104,15 +104,18 @@
       "to": "config-file.html"
     },
     {
-      "from": "documentation/docsearch-autocomplete/customize-autocomplete-styles/index.html",
+      "from":
+        "documentation/docsearch-autocomplete/customize-autocomplete-styles/index.html",
       "to": "styling.html"
     },
     {
-      "from": "documentation/docsearch-autocomplete/configuring-the-search/index.html",
+      "from":
+        "documentation/docsearch-autocomplete/configuring-the-search/index.html",
       "to": "behavior.html"
     },
     {
-      "from": "documentation/docsearch-FAQ/customize-configuration-file/index.html",
+      "from":
+        "documentation/docsearch-FAQ/customize-configuration-file/index.html",
       "to": "config-file.html"
     },
     {

docs/package.json

@@ -5,7 +5,11 @@
     "build": "NODE_ENV=production babel-node ./scripts/build.js",
     "deploy": "./scripts/deploy",
     "lint": "./scripts/lint",
-    "precommit": "./scripts/precommit",
+    "lint:js": "./scripts/lint-js",
+    "lint:css": "./scripts/lint-css",
+    "lint:md": "./scripts/lint-md",
+    "lint:md:fix": "./scripts/lint-md-fix",
+    "prepush": "./scripts/prepush",
     "serve": "babel-node ./scripts/serve.js"
   },
   "devDependencies": {
@@ -50,6 +54,14 @@
     "prettier": "1.9.2",
     "pug": "^2.0.3",
     "puppeteer": "^1.6.1",
+    "remark-cli": "^5.0.0",
+    "remark-frontmatter": "^1.2.1",
+    "remark-lint-no-trailing-spaces": "^2.0.0",
+    "remark-preset-lint-consistent": "^2.0.2",
+    "remark-preset-lint-markdown-style-guide": "^2.1.2",
+    "remark-preset-lint-recommended": "^3.0.2",
+    "remark-reference-links": "^4.0.2",
+    "remark-word-wrap": "^2.0.2",
     "stylelint": "^9.3.0",
     "stylelint-csstree-validator": "^1.3.0",
     "tailwindcss": "^0.6.4"

docs/scripts/deploy

@@ -1,6 +1,8 @@
 #!/usr/bin/env sh
 set -e
 
+yarn run lint
+
 rm -rf ./dist
 yarn run build
 gh-pages -d dist

docs/scripts/lint

@@ -1,5 +1,6 @@
 #!/usr/bin/env sh
 set -e
 
-eslint ./scripts/**/*.js ./src/*.js ./*.js
-stylelint ./src/style.css ./src/_styles/*.css
+yarn run lint:js
+yarn run lint:css
+# yarn run lint:md

docs/scripts/lint-css

@@ -0,0 +1,3 @@
+#!/usr/bin/env sh
+
+stylelint ./src/style.css ./src/_styles/*.css

docs/scripts/lint-js

@@ -0,0 +1,7 @@
+#!/usr/bin/env sh
+
+eslint \
+  ./*.js \
+  ./.*.js \
+  ./src/**/*.js \
+  ./scripts/**/*.js

docs/scripts/lint-md

@@ -0,0 +1,7 @@
+#!/usr/bin/env sh
+
+remark \
+  --no-stdout \
+  --quiet \
+  --frail \
+  ./src/*.md

docs/scripts/lint-md-fix

@@ -0,0 +1,7 @@
+#!/usr/bin/env sh
+
+REMARK_MODE=fix \
+  remark \
+    --quiet \
+    --output ./src/updated.md \
+    ./src/test.md

docs/src/apply.md

@@ -4,7 +4,6 @@ title: Applying to DocSearch
 includeForm: true
 ---
 
-__Please make sure you [read the checklist][1] before applying.__
-
+**Please make sure you [read the checklist][1] before applying.**
 
 [1]: who-can-apply.html

docs/src/behavior.md

@@ -29,6 +29,7 @@ redirect the browser to the page matching part of the page, but you can override
 it to add your own behavior.
 
 The method is called with three arguments:
+
 - `input`, a reference to the search `input` element. It comes with the `.open()`,
   `.close()`, `.getVal()` and `.setVal()` methods.
 - `event`, the actual event triggering the selection. This can come from a click
@@ -114,6 +115,8 @@ docsearch({
 
 
 [1]: https://github.com/algolia/autocomplete.js
+
 [2]: https://github.com/algolia/autocomplete.js#options
+
 [3]: https://www.algolia.com/doc/api-reference/api-parameters/
 [4]: https://www.algolia.com/doc/api-reference/api-parameters/hitsPerPage/

docs/src/run-your-own.md

@@ -3,51 +3,54 @@ layout: two-columns
 title: Run your own
 ---
 
-The version of DocSearch we provide for free is one hosted on our own servers,
-running every 24 hours. If you need to update your results more often than that,
-or need to index content sitting behind a firewall, you might want to run the
-crawler yourself.
+The version of DocSearch we provide for free is one hosted on our own
+servers, running every 24 hours. If you need to update your results
+more often than that, or need to index content sitting behind a
+firewall, you might want to run the crawler yourself.
 
-The code of DocSearch is Open-Source, and we packaged it as a Docker image to
-make this even easier for you to use.
+The code of DocSearch is Open-Source, and we packaged it as a Docker
+image to make this even easier for you to use.
 
 ## Installation
 
-Start by cloning [the repo][1] and then running `./docsearch docker:build` to
-create the local image.
+Start by cloning [the repo][1] and then running `./docsearch
+docker:build` to create the local image.
 
-Even if not recommended, you can run DocSearch directly from you host. For
-that, you'll need to have `python` and `pip` installed, and then run `pip
-install --user -r requirements.txt`.
+Even if not recommended, you can run DocSearch directly from you host.
+For that, you'll need to have `python` and `pip` installed, and then
+run `pip install --user -r requirements.txt`.
 
 ## Configuration
 
-You'll need to set your Algolia application ID and admin API key as environment
-variables. If you don't have an Algolia account, you should [create one][2].
+You'll need to set your Algolia application ID and admin API key as
+environment variables. If you don't have an Algolia account, you
+should [create one][2].
 
 - `APPLICATION_ID` should be set to your Application ID
-- `API_KEY` should be set to your API Key. Make sure to use an API key with
-  **write** access to your index.
 
-For convenience, you can create a `.env` file in the repository root with the
-following format and DocSearch will use those values.
+- `API_KEY` should be set to your API Key. Make sure to use an API key
+  with **write** access to your index.
 
-```
+For convenience, you can create a `.env` file in the repository root
+with the following format and DocSearch will use those values.
+
+```sh
 APPLICATION_ID=YOUR_APP_ID
 API_KEY=YOUR_API_KEY
 ```
 
 ## Creating a new config
 
-To create your config, run `./docsearch bootstrap`. A prompt will ask you for
-a some information and will then output a JSON config you can use as a base.
+To create your config, run `./docsearch bootstrap`. A prompt will ask
+you for a some information and will then output a JSON config you can
+use as a base.
 
 ```sh
 $ ./docsearch bootstrap
 # Enter your documentation url
-start url: http://www.example.com/docs/ 
+start url: http://www.example.com/docs/
 # You most probably don't need variables
-Does the start_urls require variables ? [y/n]: n 
+Does the start_urls require variables ? [y/n]: n
 # Pick another name, or press enter
 index_name is example [enter to confirm]: <Enter>
 
@@ -70,42 +73,43 @@ index_name is example [enter to confirm]: <Enter>
 =================
 ```
 
-Copy-paste the content into a file name `example.json`, we'll use it later to
-start the crawling. You can find the complete list of available options in [our
-documentation][3], or browse the [list of live configs][4].
+Copy-paste the content into a file name `example.json`, we'll use it
+later to start the crawling. You can find the complete list of
+available options in [our documentation][3], or browse the [list of
+live configs][4].
 
 ## Running your config
 
-Now that you have your environment variables set, you can run the crawler
-according to your config.
+Now that you have your environment variables set, you can run the
+crawler according to your config.
 
 ```sh
 $ ./docsearch docker:run /path/to/your/config.json
 ```
 
-This will crawl all pages, extract content from them and then push it to
-Algolia.
+This will crawl all pages, extract content from them and then push it
+to Algolia.
 
 ## Testing your results
 
-You can test your results by running `./docsearch playground`. This will open
-a web page with a search input where you can do live tests against the indexed
-results.
+You can test your results by running `./docsearch playground`. This
+will open a web page with a search input where you can do live tests
+against the indexed results.
 
 <img src="./assets/playground.png" alt="Playground" class="mt-2"/>
 
-_Note that if the command fails (it can happen on non-Mac machines), you can get
-the same result by running a live server in the `./playground` subdirectory.`_
+_Note that if the command fails (it can happen on non-Mac machines),
+you can get the same result by running a live server in the `
+./playground` subdirectory.\`_
 
 ## Integration
 
-Once you're satisfied with your config, you can integrate the dropdown menu in
-your website by following the [instructions here][5].
+Once you're satisfied with your config, you can integrate the dropdown
+menu in your website by following the [instructions here][5].
 
 The difference is that you'll also have to add the `appId` key to your
-`docsearch()` instance. Also don't forget to use a **search** API key here (ie.
-not the **write** API key you used for the crawling).
-
+`docsearch()` instance. Also don't forget to use a **search** API key
+here (ie. not the **write** API key you used for the crawling).
 
 ```javascript
 docsearch({
@@ -117,14 +121,18 @@ docsearch({
 
 ## Help
 
-You can run `./docsearch` without any argument to see the list of all available
-commands.
+You can run `./docsearch` without any argument to see the list of all
+available commands.
 
-Note that we use this CLI tool internally at Algolia to run the free hosted
-version, so you might not need all the listed commands.
+Note that we use this CLI tool internally at Algolia to run the free
+hosted version, so you might not need all the listed commands.
 
 [1]: https://github.com/algolia/docsearch-scraper
+
 [2]: https://www.algolia.com/pricing#community
+
 [3]: ./config-file.html
+
 [4]: https://github.com/algolia/docsearch-configs/tree/master/configs
+
 [5]: ./dropdown.html

docs/src/styling.md

@@ -87,8 +87,6 @@ two-column layout shown in the screenshot is used on larger screens. You can
 media queries (for example `@media (min-width: 768px) {}`) to target one or the
 other display.
 
-
-
 ## Advanced styling
 
 If you want to more heavily style the results, feel free to have a look at the
@@ -99,8 +97,10 @@ You can generate your own CSS file by cloning the repo and running `yarn run
 build:css`. The resulting file will be generated in `./dist/cdn`, and should be
 used instead of the default one.
 
-
 [1]: ./assets/default-colorscheme.png
+
 [2]: https://www.algolia.com/pricing
+
 [3]: ./crawler-overview.html
+
 [4]: https://github.com/algolia/docsearch/tree/master/src/styles

docs/src/test.md

@@ -0,0 +1,9 @@
+---
+layout: two-columns
+title: Tips for a good search
+---
+
+DocSearch can work with almost any website, but we found that some
+site structure yield more relevant result and/or faster indexing time.
+In this page we'll share some tips on how you can make the most out of
+DocSearch.

docs/src/tips.md

@@ -75,5 +75,4 @@ class to the `Installation` and `Troubleshooting` links in your sidebar.
 The name of the CSS class does not matter, as long as it's something that can be
 used as part of a CSS selector.
 
-
 [1]: https://www.sitemaps.org/index.html

docs/src/updated.md

@@ -0,0 +1,9 @@
+---
+layout: two-columns
+title: Tips for a good search
+---
+
+DocSearch can work with almost any website, but we found that some
+site structure yield more relevant result and/or faster indexing time.
+In this page we'll share some tips on how you can make the most out of
+DocSearch.

docs/src/what-is-docsearch.md

@@ -6,7 +6,7 @@ title: What is DocSearch?
 DocSearch is born out of the need to scratch our own itch. As developers, we
 spent a lot of time reading documentation, and we often found it hard to find
 relevant information we need quickly. We're not blaming anyone here; building
-a good search is a challenge. 
+a good search is a challenge.
 
 It just happens that we are a search company and we actually have a lot of
 experience building search interfaces. We wanted to put those skills to good

docs/src/who-can-apply.md

@@ -18,12 +18,15 @@ points:
 
 - You must be the **owner** of the website, or at least have the power to update
   its content. You'll have to include a JavaScript snippet to enable DocSearch.
+
 - Your website must be **publicly available**. We cannot index websites that are
   sitting behind an authentication or available on your machine.
+
 - Your website must be a **documentation website**. We do not index blogs and
   commercial one-pagers.
-- Your website must **have some content**. We won't index empty websites nor those
-  filled with lorem ipsum placeholder content. Please, wait until you have
+
+- Your website must **have some content**. We won't index empty websites nor
+  those filled with lorem ipsum placeholder content. Please, wait until you have
   written some documentation before applying.
 
 If in doubt, don't hesitate to [apply][1] and we'll figure it out together.
@@ -42,13 +45,14 @@ following criteria:
 - 🙂 If your project is Open-Source, we'll handle it before any other
   close-source product. We care about the OSS community and want to help as much
   as we can.
+
 - 🙂 If you're using one of our [official integrations][2], creating your config
   will be much faster for us.
+
 - ☹️ If your website is rendered in the browser through JavaScript, it means
   that we'll have to crawl it through a browser emulation which is much slower
   than a typical crawl. We highly recommend that you implement server-side
   rendering if you can.
 
-
 [1]: ./apply.html
 [2]: ./integrations.html

package.json

@@ -16,7 +16,8 @@
     "release:beta": "./scripts/release-beta",
     "serve": "./scripts/serve",
     "test": "./scripts/test",
-    "test:watch": "./scripts/test-watch"
+    "test:watch": "./scripts/test-watch",
+    "postinstall": "cd ./docs && yarn install"
   },
   "files": [
     "dist/"