docs(lint): Lint natural language texts
This commit is contained in:
Pixelastic
parent
56eb485b5b
commit
dfc12b4b5e
18 changed files with 77 additions and 80 deletions
11
docs/.textlintrc.js
Normal file
11
docs/.textlintrc.js
Normal file
|
|
@ -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"
|
||||
],
|
||||
},
|
||||
},
|
||||
};
|
||||
|
|
@ -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._
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -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": {
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -5,3 +5,7 @@ REMARK_MODE=fix \
|
|||
--quiet \
|
||||
./src/*.md \
|
||||
--output
|
||||
|
||||
textlint \
|
||||
--fix \
|
||||
./src/*.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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
{
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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 (`<p>` 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 (`<p>` 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
|
||||
|
|
|
|||
|
|
@ -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({
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue