From 91fa78c315de2cee1e7e549b827c686499517a02 Mon Sep 17 00:00:00 2001 From: Pixelastic Date: Wed, 22 Aug 2018 19:55:20 +0200 Subject: [PATCH] Add Markdown linting --- docs/.eslintignore | 1 + docs/.remarkrc.js | 38 ++++++++++++ docs/config.json | 11 ++-- docs/package.json | 14 ++++- docs/scripts/deploy | 2 + docs/scripts/lint | 5 +- docs/scripts/lint-css | 3 + docs/scripts/lint-js | 7 +++ docs/scripts/lint-md | 7 +++ docs/scripts/lint-md-fix | 7 +++ docs/scripts/{precommit => prepush} | 0 docs/src/apply.md | 3 +- docs/src/behavior.md | 3 + docs/src/run-your-own.md | 94 ++++++++++++++++------------- docs/src/styling.md | 6 +- docs/src/test.md | 9 +++ docs/src/tips.md | 1 - docs/src/updated.md | 9 +++ docs/src/what-is-docsearch.md | 2 +- docs/src/who-can-apply.md | 10 ++- package.json | 3 +- 21 files changed, 174 insertions(+), 61 deletions(-) create mode 100644 docs/.eslintignore create mode 100644 docs/.remarkrc.js create mode 100755 docs/scripts/lint-css create mode 100755 docs/scripts/lint-js create mode 100755 docs/scripts/lint-md create mode 100755 docs/scripts/lint-md-fix rename docs/scripts/{precommit => prepush} (100%) create mode 100644 docs/src/test.md create mode 100644 docs/src/updated.md diff --git a/docs/.eslintignore b/docs/.eslintignore new file mode 100644 index 00000000..93bbd9bd --- /dev/null +++ b/docs/.eslintignore @@ -0,0 +1 @@ +!.*.js diff --git a/docs/.remarkrc.js b/docs/.remarkrc.js new file mode 100644 index 00000000..6ec248af --- /dev/null +++ b/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; diff --git a/docs/config.json b/docs/config.json index 8caf5758..1ee0b18e 100644 --- a/docs/config.json +++ b/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" }, { diff --git a/docs/package.json b/docs/package.json index 67a37d94..cae4dfc4 100644 --- a/docs/package.json +++ b/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" diff --git a/docs/scripts/deploy b/docs/scripts/deploy index 621f0b1e..4b4e5de3 100755 --- a/docs/scripts/deploy +++ b/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 diff --git a/docs/scripts/lint b/docs/scripts/lint index 1aba1ac3..ebc58f44 100755 --- a/docs/scripts/lint +++ b/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 diff --git a/docs/scripts/lint-css b/docs/scripts/lint-css new file mode 100755 index 00000000..25bdc77e --- /dev/null +++ b/docs/scripts/lint-css @@ -0,0 +1,3 @@ +#!/usr/bin/env sh + +stylelint ./src/style.css ./src/_styles/*.css diff --git a/docs/scripts/lint-js b/docs/scripts/lint-js new file mode 100755 index 00000000..817bae6d --- /dev/null +++ b/docs/scripts/lint-js @@ -0,0 +1,7 @@ +#!/usr/bin/env sh + +eslint \ + ./*.js \ + ./.*.js \ + ./src/**/*.js \ + ./scripts/**/*.js diff --git a/docs/scripts/lint-md b/docs/scripts/lint-md new file mode 100755 index 00000000..631a0dec --- /dev/null +++ b/docs/scripts/lint-md @@ -0,0 +1,7 @@ +#!/usr/bin/env sh + +remark \ + --no-stdout \ + --quiet \ + --frail \ + ./src/*.md diff --git a/docs/scripts/lint-md-fix b/docs/scripts/lint-md-fix new file mode 100755 index 00000000..2d9cee1b --- /dev/null +++ b/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 diff --git a/docs/scripts/precommit b/docs/scripts/prepush similarity index 100% rename from docs/scripts/precommit rename to docs/scripts/prepush diff --git a/docs/src/apply.md b/docs/src/apply.md index 2247cead..34fc3828 100644 --- a/docs/src/apply.md +++ b/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 diff --git a/docs/src/behavior.md b/docs/src/behavior.md index c249c927..00e1b57c 100644 --- a/docs/src/behavior.md +++ b/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/ diff --git a/docs/src/run-your-own.md b/docs/src/run-your-own.md index 5fedb319..9dc62adb 100644 --- a/docs/src/run-your-own.md +++ b/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]: @@ -70,42 +73,43 @@ index_name is example [enter to confirm]: ================= ``` -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. Playground -_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 diff --git a/docs/src/styling.md b/docs/src/styling.md index da121d2a..316556b8 100644 --- a/docs/src/styling.md +++ b/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 diff --git a/docs/src/test.md b/docs/src/test.md new file mode 100644 index 00000000..26946034 --- /dev/null +++ b/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. diff --git a/docs/src/tips.md b/docs/src/tips.md index d374fb60..0470b834 100644 --- a/docs/src/tips.md +++ b/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 diff --git a/docs/src/updated.md b/docs/src/updated.md new file mode 100644 index 00000000..26946034 --- /dev/null +++ b/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. diff --git a/docs/src/what-is-docsearch.md b/docs/src/what-is-docsearch.md index 0444d0f7..acbcf3f3 100644 --- a/docs/src/what-is-docsearch.md +++ b/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 diff --git a/docs/src/who-can-apply.md b/docs/src/who-can-apply.md index bf8b1635..5b15c68f 100644 --- a/docs/src/who-can-apply.md +++ b/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 diff --git a/package.json b/package.json index 0ff4cc35..43454220 100644 --- a/package.json +++ b/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/"