diff --git a/docs/.textlint.terms.json b/docs/.textlint.terms.json new file mode 100644 index 00000000..27a35ece --- /dev/null +++ b/docs/.textlint.terms.json @@ -0,0 +1,209 @@ +[ + "3D", + "API", + "Airbnb", + "Ajax", + "Algolia", + "Android", + "BrowserStack", + "Browsersync", + "CSS", + "CodePen", + "CodeSandbox", + "Codecov", + "DocSearch", + "ECMAScript", + "ESLint", + "EditorConfig", + "GIF", + "GitHub", + "GraphQL", + "HTML", + "HTTPS", + "ID", + "InstantSearch", + "IoT", + "I/O", + "JPEG", + "JavaScript", + "JetBrains", + "LinkedIn", + "Lodash", + "MIME", + "MacBook", + "Markdown", + "OK", + "OpenType", + "PDF", + "PNG", + "PaaS", + "SaaS", + "Sass", + "SemVer", + "TypeScript", + "URL", + "UglifyJS", + "WebStorm", + "WordPress", + "YouTube", + "advancedSyntax", + "allowCompressionOfIntegerArray", + "allowTyposOnNumericTokens", + "alternativesAsExact", + "analyticsTags", + "aroundLatLngViaIP", + "aroundLatLng", + "aroundPrecision", + "aroundRadius", + "aroundRadius", + "attributeForDistinct", + "attributesForFaceting", + "attributesToHighlight", + "attributesToRetrieve", + "attributesToSnippet", + "camelCaseAttributes", + "clickAnalytics", + "customRanking", + "decompoundedAttributes", + "disableExactOnAttributes", + "disablePrefixOnAttributes", + "disableTypoToleranceOnAttributes", + "disableTypoToleranceOnWords", + "enableRules", + "exactOnSingleWordQuery", + "e-commerce", + "facetFilters", + "facetingAfterDistinct", + "getRankingInfo", + "highlightPostTag", + "highlightPreTag", + "hitsPerPage", + "iOS", + "ignorePlurals", + "insideBoundingBox", + "insidePolygon", + "jQuery", + "maxFacetHits", + "maxValuesPerFacet", + "minProximity", + "minWordSizefor1Typo", + "minWordSizefor2Typos", + "minimumAroundRadius", + "npm", + "numericAttributesForFiltering", + "numericFilters", + "open source", + "optionalFilters", + "optionalWords", + "pagehitsPerPagepagination", + "paginationLimitedTo", + "percentileComputation", + "queryType", + "removeStopWords", + "removeWordsIfNoResults", + "replaceSynonymsInHighlight", + "responseFields", + "restrictHighlightAndSnippetArrays", + "restrictSearchableAttributes", + "ruleContexts", + "searchableAttributes", + "searchableAttributes", + "separatorsToIndex", + "snippetEllipsisText", + "sortFacetValuesBy", + "sumOrFiltersScores", + "tagFilters", + "typoTolerance", + "unretrievableAttributes", + ["3-D", "3D"], + ["Aloglia", "Algolia"], + ["CLI tool(s?)", "command-line tool$1"], + ["HTTP[ /]2(?:\\.0)?", "HTTP/2"], + ["I-O", "I/O"], + ["JSDocs?", "JSDoc"], + ["Mac ?OS", "macOS"], + ["Nodejs", "Node.js"], + ["OS X", "macOS"], + ["React[ .]js", "React"], + ["SauceLabs", "Sauce Labs"], + ["StackOverflow", "Stack Overflow"], + ["an URL", "a URL"], + ["auto[- ]complete", "autocomplete"], + ["auto[- ]fixing", "autofixing"], + ["auto[- ]fix", "autofix"], + ["auto[- ]format", "autoformat"], + ["a npm", "an npm"], + ["backwards compatible", "backward compatible"], + ["back[- ]end(\\w*)", "backend$1"], + ["bug[- ]fix(es?)", "bugfix$1"], + ["build system(s?)", "build tool$1"], + ["built ?in", "built-in"], + ["check[- ]box(es?)", "checkbox$1"], + ["client ?side", "client-side"], + ["code-?review(s?)", "code review$1"], + ["code-?splitting", "code splitting"], + ["code[- ]base(es?)", "codebase$1"], + ["command ?line", "command-line"], + ["co[- ]locate(d?)", "colocate$1"], + ["css-?in-?js", "CSS in JS"], + ["datas", "data"], + ["ecommerce", "e-commerce"], + ["end ?to ?end", "end-to-end"], + ["end-?user(s?)", "end user$1"], + ["end[- ]point(s?)", "endpoint$1"], + ["environemnt(s?)", "environment$1"], + ["error ?prone", "error-prone"], + ["e commerce", "e-commerce"], + ["e[- ]mail(s?)", "email$1"], + ["falsey", "falsy"], + ["feedbacks", "feedback"], + ["file-?type(s?)", "file type$1"], + ["file[- ]name(s?)", "filename$1"], + ["front[- ]end(\\w*)", "frontend$1"], + ["he or she", "they"], + ["he/she", "they"], + ["higher ?order", "higher-order"], + ["host[- ]name(s?)", "hostname$1"], + ["hot[- ]key(s?)", "hotkey$1"], + ["id(s?)", "ID$1"], + ["informations", "information"], + ["key[/ ]?value", "key-value"], + ["life[- ]cycle", "lifecycle"], + ["life[- ]stream(s?)", "lifestream$1"], + ["lock[- ]file(s?)", "lockfile$1"], + ["mark-up", "markup"], + ["meta[- ]data", "metadata"], + ["name[- ]space(s?)", "namespace$1"], + ["one URLs", "one URL"], + ["opensource([\\.,]?)", "open source$1"], + ["open-source([\\.,]?)", "open source$1"], + ["pacakge(s?)", "package$1"], + ["pre[- ]condition(s?)", "precondition$1"], + ["pre[- ]defined", "predefined"], + ["pre[- ]release(s?)", "prerelease$1"], + ["regexp?(s?)", "regular expression$1"], + ["repo\\b", "repository"], + ["run[- ]time", "runtime"], + ["screen[- ]shot(s?)", "screenshot$1"], + ["screen[- ]?snap(s?)", "screenshot$1"], + ["server ?side", "server-side"], + ["slave(s?)", "replica$1"], + ["smartphone(s?)", "mobile phone$1"], + ["source-?map(s?)", "source map$1"], + ["styled ?components", "styled-components"], + ["style-?guide(s?)", "style guide$1"], + ["style-?sheet(s?)", "style sheet$1"], + ["sub[- ]class((?:es|ing)?)", "subclass$1"], + ["sub[- ]tree(s?)", "subtree$1"], + ["tilda", "tilde"], + ["time[- ]stamp(s?)", "timestamp$1"], + ["touch[- ]screen(s?)", "touchscreen$1"], + ["tree-?shaking", "tree shaking"], + ["user-?base", "user base"], + ["user[- ]name(s?)", "username$1"], + ["walk[- ]through", "walkthrough"], + ["web-?page(s?)", "web page$1"], + ["white[- ]space", "whitespace"], + ["wild[- ]card(s?)", "wildcard$1"], + ["wi[- ]?fi", "Wi-Fi"] +] diff --git a/docs/.textlintrc.js b/docs/.textlintrc.js index 55b11344..7c4ef1fc 100644 --- a/docs/.textlintrc.js +++ b/docs/.textlintrc.js @@ -2,6 +2,11 @@ module.exports = { rules: { 'common-misspellings': true, + 'en-capitalization': true, + terminology: { + defaultTerms: false, + terms: `${__dirname}/.textlint.terms.json`, + }, '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 44715deb..b1957b13 100644 --- a/docs/README.md +++ b/docs/README.md @@ -32,20 +32,20 @@ to the `gh-pages` branch and push it to GitHub. ## Internals The documentation generation is not using any existing static websites -generators, but custom javascript scripts. +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 -All markdown files situated in `./src` will be transformed into `.html` files in +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. All the headers will be converted to their respective `` tag, along with a unique `#id` to allow for easy anchoring. -You can also use plain HTML inside those markdown files if you need more +You can also use plain HTML inside those Markdown files if you need more advanced styling. ### Layouts @@ -122,7 +122,7 @@ element extracted from the markup of the current page. ### 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 +a `from` and a `to` key. For each `from`, it will create a plain HTML page at this location, that will redirect anyone visiting it to the page defined in `to`. diff --git a/docs/package.json b/docs/package.json index a809bf5a..15c0ffbe 100644 --- a/docs/package.json +++ b/docs/package.json @@ -66,7 +66,9 @@ "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" + "textlint-rule-en-capitalization": "^2.0.1", + "textlint-rule-stop-words": "^1.0.4", + "textlint-rule-terminology": "^1.1.29" }, "peerDependencies": {}, "dependencies": { diff --git a/docs/src/config-file.md b/docs/src/config-file.md index 5be3cc22..64480dd4 100644 --- a/docs/src/config-file.md +++ b/docs/src/config-file.md @@ -44,7 +44,7 @@ like. ## `start_urls` -This array contains the list of urls that will be used to start crawling your +This array contains the list of URLs that will be used to start crawling your website. The crawler will recursively follow any links on those pages. It will not follow links that are on another domain and never follow links defined in `stop_urls`. @@ -85,7 +85,7 @@ have `lang: en` and `version: latest` added to it, allowing you to then filter based on those values. The following example shows how you can filter results matching specifics -language and version from the front-end +language and version from the frontend ```js docsearch({ @@ -126,7 +126,7 @@ docsearch({ ### Using Page Rank 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 +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. @@ -452,8 +452,8 @@ use it to define which pages to crawl. ### `sitemap_urls` _Optional_ -You can pass an array of urls pointing to your sitemap(s) files. If this value -is set, DocSearch will try to read urls from your sitemap(s) instead of +You can pass an array of URLs pointing to your sitemap(s) files. If this value +is set, DocSearch will try to read URLs from your sitemap(s) instead of following every link of your `starts_urls`. ```json @@ -466,9 +466,9 @@ following every link of your `starts_urls`. ### `sitemap_alternate_links` _Optional_ -Sitemaps can contain _alternative links_ for urls. Those are other versions of -the same page, in a different language, or with a different url. By default -DocSearch will ignore those urls. +Sitemaps can contain _alternative links_ for URLs. Those are other versions of +the same page, in a different language, or with a different URL. By default +DocSearch will ignore those URLs. Set this to `true` if you want those other version to be crawled as well. @@ -504,7 +504,7 @@ encourage you to update your website to enable server-side rendering._ ### `js_render` _Optional_ Set this value to true if your website requires client-side rendering. This will -make DocSearch spawn a Selenium proxy to fetch all your webpages. +make DocSearch spawn a Selenium proxy to fetch all your web pages. ```json { @@ -534,7 +534,7 @@ This option has no impact if `js_render` is set to `false`. ### `use_anchors` _Optional_ Websites using client-side rendering often don't use full urls, but instead take -advantage of the url hash (the part after the `#`). +advantage of the URL hash (the part after the `#`). If your website is using such urls, you should set `use_anchors` to `true` for DocSearch to index all your content. diff --git a/docs/src/crawler-overview.md b/docs/src/crawler-overview.md index 0bc83e34..e3968be0 100644 --- a/docs/src/crawler-overview.md +++ b/docs/src/crawler-overview.md @@ -22,7 +22,7 @@ We run this service entirely free of charge, we're just asking that you keep the "powered by Algolia" logo next to the search results. That being said, if you'd like to run DocSearch on your own, [all the code is -open-source][3] and even packaged as a Docker image. Just grab it, and run it +open source][3] and even packaged as a Docker image. Just grab it, and run it with your own credentials. [1]: https://scrapy.org/ diff --git a/docs/src/faq.md b/docs/src/faq.md index 476ba359..937890f5 100644 --- a/docs/src/faq.md +++ b/docs/src/faq.md @@ -63,6 +63,7 @@ more complete information in our [privacy policy][6]. The free DocSearch we provide will crawl documentation pages. If you want to use it on other parts of your website, you'll need to create your own Algolia account and either: + You need to use the searchableAttributes and attributesForFaceting. - Run the [DocSearch crawler][7] on your own - Use one of our other [framework integrations or API clients][8] @@ -72,6 +73,7 @@ account and either: Yes, but we do not recommend it. Code samples are a great way for humans to understand how a specific pattern +ap alpha / method should be used. It often requires boilerplate code though, repeated across examples, which will add noise to the results. @@ -81,12 +83,12 @@ content so the method names are actual headers. ### Why do I have duplicate content in my results? -This can happen when you have more than one urls pointing to the same content, +This can happen when you have more than one URL pointing to the same content, for example with `./docs`, `./docs/` and `./docs/index.html` or even both `http` and `https` in place. This can be fixed by `stop_urls` to all the patterns you want to exclude. The -following example will exclude all urls ending with `/` or `index.html` as well +following example will exclude all URLs ending with `/` or `index.html` as well as those starting with `http://`. ```json diff --git a/docs/src/how-does-it-work.md b/docs/src/how-does-it-work.md index e07da6a7..77961262 100644 --- a/docs/src/how-does-it-work.md +++ b/docs/src/how-does-it-work.md @@ -5,11 +5,11 @@ title: How does it work? Getting up and ready with DocSearch is a straightforward process that requires a three steps: you apply, we configure the crawler for you, and you update your -front-end. +frontend. How it works -### 1. You apply +### You apply The first thing you'll need to do is to apply for DocSearch by filling the form on this page (make sure to double check that you qualify first). We are @@ -19,19 +19,19 @@ anyone. 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 +### We create a configuration Once we receive your application, we'll have a look at your website and create -a custom configuration file for it. This file defines which urls we +a custom configuration file for it. This file defines which URLs we should crawl or ignore, as well as the specific CSS selectors to be used for selecting headers, subheaders, etc. All configs are publicly available in our -[config repo][1]. +[config repository][1]. This step still requires some manual work, but thanks to the 900+ configs we already created, we're able to automate most of it. Once done, we'll run a first indexing of your website and have it run automatically every 24h. -### 3. You update your website +### You update your website We'll then get back to you with the JavaScript snippet you'll need to add to your website. This will bind your search `input` field to display results from diff --git a/docs/src/run-your-own.md b/docs/src/run-your-own.md index 85d82c72..a56830c6 100644 --- a/docs/src/run-your-own.md +++ b/docs/src/run-your-own.md @@ -8,12 +8,12 @@ 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 +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 +Start by cloning [the repository][1] and then running `./docsearch docker:build` to create the local image. Even if not recommended, you can run DocSearch directly from you host. @@ -73,7 +73,7 @@ index_name is example [enter to confirm]: ================= ``` -Copy-paste the content into a file name `example.json`, we'll use it +Copy-paste the content into a filename `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]. @@ -123,7 +123,7 @@ docsearch({ 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 +Note that we use this command-line 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 diff --git a/docs/src/styling.md b/docs/src/styling.md index a63aaf13..6e2aac74 100644 --- a/docs/src/styling.md +++ b/docs/src/styling.md @@ -55,7 +55,7 @@ and you're encouraged to style it to fit your own theming. All we ask is that you keep the `search by Algolia` logo and link next to your search results. The logo is automatically added in the dropdown with the default styling. It's -ok to hide it through CSS, as long as you re-add it somewhere else on your page +OK to hide it through CSS, as long as you re-add it somewhere else on your page close to the search input or search results. It's our way to let more people know about what do, and how they could also have from fast and relevant search on their website. @@ -93,9 +93,9 @@ 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. -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. +You can generate your own CSS file by cloning the repository 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 diff --git a/docs/src/what-is-docsearch.md b/docs/src/what-is-docsearch.md index 42d67831..a871b4ab 100644 --- a/docs/src/what-is-docsearch.md +++ b/docs/src/what-is-docsearch.md @@ -13,9 +13,9 @@ 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 +DocSearch itself is made of a crawler and a frontend library. We run the crawler on our end every 24h to extract content from your website and push it to -an Algolia index. You'll then have to add the front-end library to your website +an Algolia index. You'll then have to add the frontend 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 @@ -24,7 +24,7 @@ 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. +to the open source community for everything it did for us already. [1]: https://opencollective.com/algolia diff --git a/docs/src/who-can-apply.md b/docs/src/who-can-apply.md index 6ca2894b..a5a7f3f8 100644 --- a/docs/src/who-can-apply.md +++ b/docs/src/who-can-apply.md @@ -32,7 +32,7 @@ points. If in doubt, don't hesitate to [apply][1] and we'll figure it out together. Even if we cannot accept your request, this does not mean that you cannot enjoy -great search on your website. DocSearch is entirely open-source and you can run +great search on your website. DocSearch is entirely open source and you can run it yourself, or use any of our other API clients to take advantage of the features of Algolia. @@ -42,8 +42,8 @@ We're receiving many requests every day, and while we strive to answer them all 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 love Open-Source and want to help as much as we can. +- 🙂 If your project is open source, We'll handle it before any other + 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.