mirror of
https://github.com/qdrant/landing_page.git
synced 2026-09-28 15:38:33 +02:00
83 lines
3.2 KiB
Markdown
83 lines
3.2 KiB
Markdown
# English grammar linter (Vale)
|
|
|
|
This repository includes `beta` rules based on the [Vale grammar linter](https://vale.sh). While the [installation instructions](https://vale.sh/docs/vale-cli/installation/#package-managers) cover Mac and Windows, I've installed Vale on Ubuntu Linux. Vale includes
|
|
installation binaries in one of their [Git repositories](https://github.com/errata-ai/vale/releases).
|
|
|
|
You can integrate [Vale as a plugin](https://vale.sh/docs/integrations/guide/) with
|
|
several different IDEs. This README illustrates integration between Vale and VSCode.
|
|
|
|
Vale pulls rules from YAML files in the `styles/` subdirectory. They include grammar rules in the following subdirectories:
|
|
|
|
- Modified rules from GitLab in the `styles/Qdrant/` subdirectory
|
|
- [Google Developer Style Guide](https://github.com/errata-ai/Google) rules, customized for Vale, in the `styles/Google` subdirectory
|
|
- Rules associated with the [write-good](https://github.com/btford/write-good) grammar linter
|
|
|
|
These rules are a "Work in Progress"; we may overrule/modify them as we use them to review Qdrant content. For example, if you find a common word / acronym that we use, you're
|
|
welcome to add it (with a PR) to our `styles/cobalt/spelling-exceptions.txt` file.
|
|
|
|
For more information, see the [Vale documentation](https://vale.sh/).
|
|
|
|
## Vale configuration
|
|
|
|
The Vale configuration file is .vale.ini. In this file, we see:
|
|
|
|
- The `StylesPath` points to rules in the `styles/` subdirectory.
|
|
- The `BasedOnStyles` parameter specifies style subdirectories.
|
|
- The `IgnoredScopes` tells Vale to ignore content such as code samples, as described in [Vale Documentation](https://vale.sh/docs/topics/config/#ignoredscopes).
|
|
|
|
Tip: If you want Vale to ignore code, surround it with code sample marks such as:
|
|
|
|
- `Vale_ignores_this`
|
|
```
|
|
Vale also ignores this
|
|
```
|
|
|
|
## Use Vale in your IDE
|
|
|
|
You can set up Vale with several different IDEs. For more information, see the
|
|
[Integrations](https://vale.sh/docs/integrations/guide/) section of the Vale documentation.
|
|
|
|
For example, you can set up a Vale plugin with the VSCode IDE, per
|
|
https://github.com/chrischinchilla/vale-vscode.
|
|
|
|
If you have problems with Vale in VSCode, you may need to:
|
|
|
|
- Restart VSCode
|
|
- Disable / re-enable the Vale plugin
|
|
- Save changes to the Markdown file that you're analyzing
|
|
|
|
If you're successful, you'll see linting messages similar to what's shown in the following screenshot:
|
|
|
|
<p align="center">
|
|
<img src="static/VSCodeDemo.png">
|
|
</p>
|
|
|
|
## Use Vale at the command line
|
|
|
|
To review your content against the given style guide rules, first navigate to
|
|
the `qdrant-landing/` directory for this repository. Then run the following
|
|
command:
|
|
|
|
```
|
|
vale /path/to/your/filename.md
|
|
```
|
|
|
|
As long as you're in the `qdrant-landing/` directory, you can use Vale at the command line to lint Markdown files in any local directory.
|
|
|
|
## Potential future options
|
|
|
|
- Include Vale in CI/CD jobs
|
|
|
|
- Set up a GitHub action
|
|
|
|
- Apply vale to articles and blog posts
|
|
|
|
- Guess: we need different rules. Default rules for documentation suggest:
|
|
|
|
- Use "second person"
|
|
- Avoid future tense
|
|
- Don't use exclamation points
|
|
- Avoid words like "easy" and "simple"
|
|
|
|
These rules generally do not apply to articles or blogs.
|