Skip to content

Latest commit

 

History

History
200 lines (130 loc) · 8.11 KB

README.md

File metadata and controls

200 lines (130 loc) · 8.11 KB
Raw

Sauce Labs Docs

Follow Sauce Labs on Twitter PRs Welcome Gitpod Ready-to-Code Deploy to Production Sauce Docs Link Checker

Sauce Labs Browser Matrix

Welcome to the sauce-docs repository. This website contains all technical documentation about Sauce Labs and its products and is built on top of Docusaurus, a modern static website generator.

Table of Contents

  1. Prerequisites
  2. Installation
  3. Local Development
    1. Building the Website
  4. Local Linters
    1. ESLint and Prettier
    2. Vale
  5. Contributing
    1. Contributing Guide
    2. Style Guide
    3. Code of Conduct

Prerequisites

  • git
  • Node.js version >= 18 or above (which can be checked by running node -v). You can use nvm for managing multiple Node versions on a single machine installed
  • Docker (optional if you want to deploy locally via a container or to test before you deploy)

Installation

  • 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

Local Development

  • 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.

Building the Website

  • 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).

Local Linters

To help ensure code quality and improve the content added to documentation, we use the following linters:

ESLint and Prettier

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 <file>/<location> --fix

#prettier
npx prettier --write '<file>/<location>'

Vale

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.

Get Started

  1. Use a package manager to install Vale. See Installation.
  2. (Optional) Install the Vale extension (errata-ai.vale-server) for Visual Studio Code.
  3. (Optional) To configure Vale in Visual Studio Code, specify the path to the project directory with the .vale.ini file for vale.valeCLI.config in the Extension Settings. For example, /Users/yourname/Documents/GitHub/sauce-docs/.vale.ini.
  4. Save/edit a file using Visual Studio Code, or run vale [filename.md] from the root folder of the repository with the command line.

Usage: Vale + VS Code

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.

Folder Structure

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 Result Types

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.

Contributing

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.

Contributing Guide

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.

Style Guide

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.

Code of Conduct

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.