Welcome to the sauce-docs
, this website contains all technical documentation about Sauce Labs and its products. This site uses Docusaurus 2, a modern static website generator.
Table of Contents
git
- Node.js
version >= 14.15.0
or above (which can be checked by running node -v). You can use nvm for managing multiple Node versions on a single machine installed - Yarn
version >= 1.22.5
(which can be checked by running yarn version). Yarn is a performant package manager for JavaScript and replaces the npm client. It is not strictly necessary but highly encouraged. - Docker (optional if you want to deploy locally via a container or to test before you deploy)
-
Pull down this repo:
git clone https://github.com/saucelabs/sauce-docs.git
-
Change directory to
sauce-docs
:cd sauce-docs
-
Install the dependencies:
npm install
-
Serve the website locally (without Algolia API Key):
npm run dev
This command builds the site and serves it on your machine's host (http://localhost:3000) and requires no Algolia API key.
-
Start the website locally (with Algolia API Key):
npm run start
This command starts a local development server and open up a browser window (http://localhost:3000). Most changes perform live updates to your server without having to restart.
-
Build the website:
npm run build
This command gathers the static content and places them in a
build
directory; which is compatible with most static content hosting services. -
Serve the website:
npm run serve
This command builds the site and serves it on your machine's host (http://localhost:3000).
To help ensure code quality and improve the content added to documentation, we use the following linters:
The doc site employs two different code quality tools:
eslint
prettier
Before each commit, a lint-staged
task runs. If you encounter no errors feel free to push your changes to your remote branch. However if you see any eslint
errors, or if you see any prettier
responses like the one below, it means you have to run eslint
and/or prettier
Forgot to run prettier?
Below are the following commands for both eslint
and prettier
that you must run:
#eslint
npx eslint . --fix
#prettier
npx prettier --write
Vale is an open source prose linter that checks the content of docs against style guide rules. The goal of a prose linter is to automate style guide checks in docs-as-code environments, so that style issues are detected before deploy or while authoring docs in the code editor.
To help adhere to the documentation style guidelines, and improve the content added to documentation, install Vale and integrate with your code editor.
You can also use Vale with the command line, though using the linter in your editor is more convenient than having to run the commands from the command line.
- Use a package manager to install Vale. See Installation.
- (Optional) Install the Vale extension (errata-ai.vale-server) for Visual Studio Code.
- (Optional) To configure Vale in Visual Studio Code, specify the path to the project directory with the
.vale.ini
file forvale.valeCLI.config
in the Extension Settings. For example, /Users/yourname/Documents/GitHub/sauce-docs/.vale.ini. - Save/edit a file using Visual Studio Code, or run
vale [filename.md]
from the root folder of the repository with the command line.
Detailed Problems View
Browse detailed information for each alert, including the file location, style, and rule ID.
Go To Rule
Navigate from an in-editor alert to a rule's implementation for the StylesPath
by clicking View Rule.
Quick Fixes
Fix word usage, capitalization, and more using Quick Fixes (macOS: cmd + ., Windows/Linux: Ctrl + .). The quick fixes feature depends on the underlying rule implementing an action that VSCode can then trigger.
The following file and folder are stored in the root directory of the sauce-docs repository.
.vale.ini
contains the Vale configuration settings. See Configuration.styles/sauce
contains the Sauce Labs style guide rules for Vale. See Styles.
Vale returns three types of results:
- Error - For branding guidelines, trademark guidelines, and anything that causes content on the documentation site to render incorrectly.
- Warning - For general style guide rules, tenets, and best practices.
- Suggestion - For technical writing style preferences that may require refactoring of documentation or updates to an exceptions list.
The Sauce Labs sauce-docs
repo is an open source project. Your contributions are highly welcomed.
Before you submit an issue or PR in GitHub, please read the following.
Read our Contributing Guide to learn about our development process, how to propose bug fixes and improvements, and how to build and test your changes.
Review our Style Guide to learn how to get the most out of your markdown and to ensure you are following our guidelines and conventions.
Sauce Labs has adopted a Code of Conduct that we expect project participants to adhere to. Please read the full text so that you can understand what actions will and will not be tolerated.