From 3c7a97178d1812c4a9be5453fd44f4794a39d8a3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nikolaus=20Ku=CC=88hn?= Date: Thu, 16 Apr 2020 21:18:32 +0200 Subject: [PATCH] docs(writing-style): overhaul README - document how to configure vscode - improve wording and chapter order --- packages/writing-style/README.md | 44 +++++++++++++++++++------------- 1 file changed, 26 insertions(+), 18 deletions(-) diff --git a/packages/writing-style/README.md b/packages/writing-style/README.md index e022794e9..6b40f9724 100644 --- a/packages/writing-style/README.md +++ b/packages/writing-style/README.md @@ -3,43 +3,51 @@ This package provides - commercetools specific writing style and terminology rules for the configurable [vale](https://errata-ai.github.io/vale/) prose linter. -- the `commercetools-vale` command-line tool which wraps a bundled vale build and calls it using the included writing style and configuration -- the `commercetools-vale-bin` command is directly calling the current bundled vale binary without passing the commercetools configuration and writing style. The configuration has to be passed separately via vale's `--config` flag. +- the `commercetools-vale` command-line tool which wraps the vale binary and calls it using the included writing style and configuration +- the `commercetools-vale-bin` command is directly calling the vale binary without passing the commercetools configuration. The `.vale.ini` configuration location has to be passed separately via vale's `--config` flag. -The base style is the [Google Developer Documentation Style Guide](https://github.com/errata-ai/Google), which is included as a copy (MIT licensed, too) and modified and enriched with commercetools specific rules. +The base style is the [Google Developer Documentation Style Guide](https://github.com/errata-ai/Google), which is included as a copy (MIT licensed, too) and modified and partially overridden with commercetools specific rules. The configuration defaults to checking `.md`, `.mdx`, `.txt`, and `.html` files, which can be overridden by calling it with a command-line parameter `commercetools-vale --glob='*.{js,md}' ./path/to/content` passing a list of [supported file format extensions](https://errata-ai.github.io/vale/formats/#formats). -> As of Nov 2019, basing off Google's styles was a pragmatic choice. Other styles like Microsoft's are attractive starting points, too. +## Automatic vale binary download for the current platform -## Downloading vale binary +This packages `postinstall` script automatically downloads the appropriate `vale` binary upon installation. This ensures a small package size and no unnecessary binary files in it. Supported platforms are Mac OS (`darwin`), Linux (`linux`), and Windows (`windows`). -This package automatically downloads the appropriate `vale` binary upon installation (running as `postinstall` script). This ensures that the package is kept as small as possible, as the `vale` binary takes up a few megabytes, and the appropriate binary is downloaded according to the operating system (`macOS`, `linux`, `windows`). - -## Downloading Google styles - -The [Google styles for vale](https://github.com/errata-ai/Google) should not be changed manually, as they are maintained by the Errata-AI team and pulled directly from their repository. To get the latest changes, run the `yarn download:google` command. - -## Linter Usage: Standalone command-line +## Standalone command-line usage 1. Install the command globally via `yarn global add @commercetools-docs/writing-style` or `npm install -g @commercetools-docs/writing-style` 1. Use it by calling `commercetools-vale ./path/to/your/content` Please don't forget to frequently update the package to get the latest styles. -## Linter Usage: In Editor plugins +## Usage in the VSCode vale plugin -In addition, you can install a matching editor plugin to get immediate feedback while authoring. -**If your plugin allows, reconfigure the command from `vale` to `commercetools-vale`**. +The [vscode-vale plugin](https://marketplace.visualstudio.com/items?itemName=testthedocs.vale) is always passing a `--config` parameter even if none is configured, so you have to separately configure the binary and the config location as follows, for example in a workspace configuration file: -The plugin [for VSCode](https://marketplace.visualstudio.com/items?itemName=testthedocs.vale) does not support such configuration yet. +```json +{ + "settings": { + "vscode-vale.path": "${workspaceFolder}/node_modules/.bin/commercetools-vale-bin", + "vscode-vale.configPath": "${workspaceFolder}/node_modules/@commercetools-docs/writing-style/.vale.ini" + } +} +``` -## Linter Usage: CI and command-line in Javascript Projects +## Usage as a `package.json` dependency 1. Add the writing-style package as a development dependency: `yarn add --dev @commercetools-docs/writing-style` 1. In your project's folder, call it from the command line via `npx commercetools-vale ./your/path/to/content` and optionally add vale command-line parameters as needed (for example `--no-wrap` on command-line jobs). - - _Tip_: Running it over your complete repository is not a good idea since it checks the complete node_modules folder which takes a long time and is not your content. + - _Tip_: Running it over your complete repository is not a good idea since it checks the complete node_modules folder which takes a long time and is not your content, so make sure to pass a relevant file selection + +## Updating the Google styles + +The [Google styles for vale](https://github.com/errata-ai/Google) should not be changed in this repository as they are maintained by the Errata-AI team and pulled directly from their repository. To get the latest changes, run the `yarn download:google` command. + +## Updating the vale version + +Update the custom `valeVersion` property in `package.json` and confirm that the artifact naming convention on vale's [GitHub releases page](https://github.com/errata-ai/vale/releases) has not changed. ## Contributing