diff --git a/docs/.textlintrc.js b/docs/.textlintrc.js new file mode 100644 index 00000000..55b11344 --- /dev/null +++ b/docs/.textlintrc.js @@ -0,0 +1,11 @@ +/* eslint-disable import/no-commonjs */ +module.exports = { + rules: { + 'common-misspellings': true, + 'stop-words': { + exclude: [ + 'relative to', // We need to talk about links "relative to the root" + ], + }, + }, +}; diff --git a/docs/README.md b/docs/README.md index ca809512..44715deb 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,11 +1,11 @@ # Documentation website This subdirectory holds the documentation website content as well as scripts to -generate it. +generate it. -# Main commands +## Main commands -## Building the website +### Building the website You can build a new version of the website by running `yarn run build` in this directory or `yarn run docs:build` at the repository root. @@ -13,7 +13,7 @@ directory or `yarn run docs:build` at the repository root. It will read all source files in `./src` and build the final static website in `./dist`. -## Local development +### Local development You can run a local copy of the documentation website by running `yarn run serve` in this directory or `yarn run docs:serve` at the repository root. @@ -21,7 +21,7 @@ serve` in this directory or `yarn run docs:serve` at the repository root. This will build the website in `./dist` and expose it on `localhost`, along with live-reload. -## Deploying the website +### Deploying the website You can deploy the website by running `yarn run deploy` in this directory or `yarn run docs:deploy` at the repository root. @@ -29,7 +29,7 @@ You can deploy the website by running `yarn run deploy` in this directory or This will build the website and then commit the content of the `./dist` folder to the `gh-pages` branch and push it to GitHub. -# Internals +## Internals The documentation generation is not using any existing static websites generators, but custom javascript scripts. @@ -37,7 +37,7 @@ generators, but custom javascript scripts. The main two entry points are `./scripts/build.js` and `./scripts/serve.js`. The second one adds a webserver with live-reload on top of the first one. -## HTML +### HTML All markdown files situated in `./src` will be transformed into `.html` files in `./dist`. They will be wrapped into the layout defined in their front-matter. @@ -48,7 +48,7 @@ a unique `#id` to allow for easy anchoring. You can also use plain HTML inside those markdown files if you need more advanced styling. -## Layouts +### Layouts All layouts are saved in the `./src/_layouts` folder. @@ -60,7 +60,7 @@ You can also use mixins or include other files from the layouts. _Note that the current layout logic is simple and might not handle complex recursive cases, but should be enough for simple cases._ -## CSS +### CSS CSS is processed through PostCSS. It expects an entry file in `./src/style.css`. @@ -75,7 +75,7 @@ Algolia brand guidelines. The final CSS files is then compressed through PurgeCSS (to keep CSS classes that are actually used) and CleanCSS (to minify it). -## JavaScript +### JavaScript JavaScript code is processed through Babel. It will compile all files situated in `./src/js`. @@ -83,16 +83,16 @@ in `./src/js`. _Note that it compiles JS, and does not bundle it. We might add Webpack/Parcel support later._ -## Assets +### Assets Any file with the following extensions found in the `./src` folder will be automatically copied to the `./dist` folder with the same folder structure: `gif`, `jpg`, `png`, `ico`, `html`, `svg` and `woff`. -## Placeholders +### Placeholders Values defined in the `placeholders` key of the `config.json` file can be used -in JavaScript and Markdown files by using the `{{key}}` syntax. +in JavaScript and Markdown files by using the `{{key}}` syntax. For example if you have: @@ -108,7 +108,7 @@ For example if you have: Every occurrence of `{{projectVersion}}` in any `.md` or `.js` file will be replaced with `1.4.2`. -## Sidebar +### Sidebar The left sidebar of the documentation is generated based on the `sidebar` key of the `config.json`. The key should contain an array where each key is a part of @@ -119,7 +119,7 @@ The layout will then automatically create all the links and color the active page. Subsections inside the current page will also be added for every `h2` element extracted from the markup of the current page. -## Redirects +### Redirects The `config.json` file can hold a `redirects` array, with object containing both a `from` and a `to` key. For each `from`, it will create a plain html page at @@ -128,8 +128,3 @@ this location, that will redirect anyone visiting it to the page defined in _Note that both those links must be defined as relative to the `site.url` value._ - - - - - diff --git a/docs/package.json b/docs/package.json index b2204bc6..a809bf5a 100644 --- a/docs/package.json +++ b/docs/package.json @@ -63,7 +63,10 @@ "remark-reference-links": "^4.0.2", "stylelint": "^9.3.0", "stylelint-csstree-validator": "^1.3.0", - "tailwindcss": "^0.6.4" + "tailwindcss": "^0.6.4", + "textlint": "^11.0.0", + "textlint-rule-common-misspellings": "^1.0.1", + "textlint-rule-stop-words": "pixelastic/textlint-rule-stop-words#master" }, "peerDependencies": {}, "dependencies": { diff --git a/docs/scripts/lint-md b/docs/scripts/lint-md index 631a0dec..82f3d953 100755 --- a/docs/scripts/lint-md +++ b/docs/scripts/lint-md @@ -1,7 +1,12 @@ #!/usr/bin/env sh +# Check text content (misspelling, weasel words, offensive writing) +textlint ./*.md ./src/*.md + +# Check markdown styling (links, spacing, etc) remark \ --no-stdout \ --quiet \ --frail \ ./src/*.md + diff --git a/docs/scripts/lint-md-fix b/docs/scripts/lint-md-fix index ae825426..93f681d2 100755 --- a/docs/scripts/lint-md-fix +++ b/docs/scripts/lint-md-fix @@ -5,3 +5,7 @@ REMARK_MODE=fix \ --quiet \ ./src/*.md \ --output + +textlint \ + --fix \ + ./src/*.md diff --git a/docs/src/behavior.md b/docs/src/behavior.md index 4e629792..478ca206 100644 --- a/docs/src/behavior.md +++ b/docs/src/behavior.md @@ -64,7 +64,7 @@ docsearch({ ## `transformData` This method will be called on all suggestions before displaying them. It -doesn't do anything by default, but we provide this hook if you want to add your +doesn't do anything by default, but we provide this hook for you to add your own logic. ```javascript diff --git a/docs/src/config-file.md b/docs/src/config-file.md index f1b05b65..5be3cc22 100644 --- a/docs/src/config-file.md +++ b/docs/src/config-file.md @@ -33,8 +33,8 @@ This is the name of the Algolia index where your records will be pushed. The `apiKey` we will share with you will be restricted to work on this index. When using the free DocSearch crawler, the `indexName` will always be the name -of the config. If you're running DocSearch yourself, you can of course use any -name you'd like. +of the config. If you're running DocSearch yourself, you can use any name you'd +like. ```json { @@ -125,7 +125,7 @@ docsearch({ ### Using Page Rank -If you want to give more weight to some pages to boost their ranking in the +To give more weight to some pages to boost their ranking in the results, you can attribute a custom `page_rank` to specific urls. Pages with highest `page_rank` will be returned before pages with a lower `page_rank`. Note that you can pass any numeric value, including negative values. @@ -365,8 +365,7 @@ a `min_indexed_level: 2`, records that have at least `lvl0`, `lvl1` and This is useful when your documentation has pages that share the same `lvl0` and `lvl1` for example. In that case, you don't want to index all the shared -records, but want to keep the one matching content that is different across -pages. +records, but want to keep the content different across pages. ```json { diff --git a/docs/src/crawler-overview.md b/docs/src/crawler-overview.md index f5a79710..0bc83e34 100644 --- a/docs/src/crawler-overview.md +++ b/docs/src/crawler-overview.md @@ -12,10 +12,9 @@ any content, and will use the semantics of your HTML structure to construct its records. This means that `h1`...`h6` titles will be used for the hierarchy, and each `p` of text will be used as a potential result. -Those CSS selectors can of course be overwritten, and each website actually has -its own JSON configuration file that describe in more details how the crawling -should behave. You can find the complete list of options in [our -documentation][2]. +Those CSS selectors can be overwritten, and each website actually has its own +JSON configuration file that describe in more details how the crawling should +behave. You can find the complete list of options in [our documentation][2]. We automatically run each config every 24h. This is done from our own infrastructure, meaning that you don't need to install anything on your side. diff --git a/docs/src/faq.md b/docs/src/faq.md index ebca36f9..476ba359 100644 --- a/docs/src/faq.md +++ b/docs/src/faq.md @@ -32,7 +32,7 @@ projects can afford. That's why we decided to keep DocSearch free for everyone. All we ask in exchange is that you keep the _powered by [Algolia][2]_ logo displayed next to the search results. -If this is not possible for you, you're totally free to [open your own Algolia +If this is not possible for you, you're free to [open your own Algolia account][3] and run DocSearch on your own without this limitation. In that case though, depending on the size of your documentation, you might need a paid account ([free accounts][4] can hold as much as 10k records). @@ -45,8 +45,8 @@ page is defined in your custom config. As the website owner, we also give you access to the Algolia Analytics dashboard, that will let you have more data about the anonymized searches that -were done on your website. You'll be able to see the most searched terms, or -those with no results. +were done on your website. You'll see the most searched terms, or those with no +results. You will understand what people do not. diff --git a/docs/src/how-does-it-work.md b/docs/src/how-does-it-work.md index c406930d..e07da6a7 100644 --- a/docs/src/how-does-it-work.md +++ b/docs/src/how-does-it-work.md @@ -16,8 +16,8 @@ form on this page (make sure to double check that you qualify first). We are receiving a lot of requests, so this form makes sure we won't be forgetting anyone. -We guarantee that we will answer to every request, but due to the amount of -applications we receive, please give us a couple of days to get back to you :) +We guarantee that we will answer to every request, but we receive a lot +of applications, so please give us a couple of days to get back to you :) ### 2. We create a configuration diff --git a/docs/src/inside-the-engine.md b/docs/src/inside-the-engine.md index 0124d059..28bc4903 100644 --- a/docs/src/inside-the-engine.md +++ b/docs/src/inside-the-engine.md @@ -18,9 +18,9 @@ all pages. ## Extracting content Then, for each page, it will read the HTML markup from top to bottom. It will -look for HTML elements matching your CSS `selectors`. It will specifically look -for elements matching your `text` selector (`

` by default). Each of those -matches will be later transformed into an Algolia record. +look for HTML elements matching your CSS `selectors`. It will look for elements +matching your `text` selector (`

` by default). Each of those matches will be +later transformed into an Algolia record. For each matching `text` element, the crawler will also keep in memory the current hierarchy of headers (identified by the `lvl0` to `lvl5` selectors) that @@ -55,8 +55,7 @@ You also have a way to boost some pages directly in your config by using the `page_rank` option. This accepts a numeric value, and all pages with a `page_rank` of 5 will be returned before pages with a `page_rank` of 1. -If you want to get fancy, you could even overwrite the default -`customRanking` used by the index by using the `custom_settings` option of -your config. +You could even overwrite the default `customRanking` used by the index by using +the `custom_settings` option of your config. [1]: https://www.algolia.com/doc/guides/ranking/ranking-formula/#tie-breaking-approach diff --git a/docs/src/run-your-own.md b/docs/src/run-your-own.md index 0f96e4b2..85d82c72 100644 --- a/docs/src/run-your-own.md +++ b/docs/src/run-your-own.md @@ -4,8 +4,8 @@ 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 +servers, running every 24 hours. To update your results +more often than that, or 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 @@ -108,7 +108,7 @@ 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). +here (in other words, not the **write** API key you used for the crawling). ```javascript docsearch({ diff --git a/docs/src/styling.md b/docs/src/styling.md index 316556b8..a63aaf13 100644 --- a/docs/src/styling.md +++ b/docs/src/styling.md @@ -65,7 +65,7 @@ yourself][3], you don't have to keep the logo. ## Debugging -If you want to inspect the dropdown markup with your browser tools, you should +To inspect the dropdown markup with your browser tools, you should add `debug: true` to your `docsearch` call to prevent it from closing on inspection. @@ -89,7 +89,7 @@ other display. ## Advanced styling -If you want to more heavily style the results, feel free to have a look at the +To more heavily style the results, feel free to have a look at the [SCSS source code][4]. `_variables.scss` contains all the default theming, sizing and breakpoints. diff --git a/docs/src/test.md b/docs/src/test.md deleted file mode 100644 index 26946034..00000000 --- a/docs/src/test.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -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 0470b834..9fd1f30c 100644 --- a/docs/src/tips.md +++ b/docs/src/tips.md @@ -4,7 +4,7 @@ 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 +structure yield more relevant result or faster indexing time. In this page we'll share some tips on how you can make the most out of DocSearch. ### Use a `sitemap.xml` @@ -47,7 +47,7 @@ recommend that you add a custom `id` to the HTML element that will be the parent of all your textual content. Having such a unique identifier will make your configuration more robust as it -will make sure all content that is indexed is relevant content. We found that +will make sure all indexed content is relevant content. We found that this is the most reliable way to exclude headers, sidebars and footers content that are not relevant to the search. diff --git a/docs/src/updated.md b/docs/src/updated.md deleted file mode 100644 index 26946034..00000000 --- a/docs/src/updated.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -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 bb7a697c..42d67831 100644 --- a/docs/src/what-is-docsearch.md +++ b/docs/src/what-is-docsearch.md @@ -9,8 +9,8 @@ relevant information we need quickly. We're not blaming anyone here; building 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 -use. That's why we created a way to automatically extract content from tech +experience building search interfaces. We wanted to use those skills to help +others. That's why we created a way to automatically extract content from tech documentation and make it available to everyone with only a few keystrokes. DocSearch itself is made of a crawler and a front-end library. We run the @@ -19,11 +19,13 @@ an Algolia index. You'll then have to add the front-end library to your website to redirect all the search requests to this index. DocSearch is entirely free and mostly automated. The only thing we'll need from -you is to check that you're eligible (most tech projects are), and apply! After -that, we'll share with you the JavaScript snippet needed to add DocSearch to -your website. We just ask that you keep the "powered by Algolia" link displayed. +you is to read [our checklist][2] and apply! After that, we'll share with you +the JavaScript snippet needed to add DocSearch to your website. We just ask that +you keep the "powered by Algolia" link displayed. DocSearch is [one of our ways][1] to give back to the Open-Source community for everything it did for us already. [1]: https://opencollective.com/algolia + +[2]: ./who-can-apply.html diff --git a/docs/src/who-can-apply.md b/docs/src/who-can-apply.md index e85a0d7e..6ca2894b 100644 --- a/docs/src/who-can-apply.md +++ b/docs/src/who-can-apply.md @@ -13,8 +13,8 @@ We hope you understand. ### The checklist -To have your request validated, please make sure you comply with the following -points: +To have your request validated, we'll ask that you valide all the following +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. @@ -43,16 +43,14 @@ as fast as we can, we sometimes give priority to some of them based on the 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. + close-source product. We love Open-Source 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. +- ☚ī¸ If your website is rendered in the browser through JavaScript, it means that + we'll have to crawl it through a much slower browser emulation. We highly + recommend that you implement server-side rendering if you can. [1]: ./apply.html