{"id":23577595,"url":"https://github.com/couchbaselabs/docs-style-guide","last_synced_at":"2026-01-24T12:08:01.272Z","repository":{"id":44994027,"uuid":"71495883","full_name":"couchbaselabs/docs-style-guide","owner":"couchbaselabs","description":"Couchbase documentation style guide","archived":false,"fork":false,"pushed_at":"2025-12-18T19:54:49.000Z","size":2366,"stargazers_count":4,"open_issues_count":3,"forks_count":30,"subscribers_count":32,"default_branch":"main","last_synced_at":"2025-12-26T16:19:54.379Z","etag":null,"topics":["docs","docs-tooling"],"latest_commit_sha":null,"homepage":"https://docs.couchbase.com/styleguide/index.html","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/couchbaselabs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2016-10-20T19:15:58.000Z","updated_at":"2025-11-27T16:29:27.000Z","dependencies_parsed_at":"2026-01-07T19:10:36.993Z","dependency_job_id":null,"html_url":"https://github.com/couchbaselabs/docs-style-guide","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/couchbaselabs/docs-style-guide","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/couchbaselabs%2Fdocs-style-guide","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/couchbaselabs%2Fdocs-style-guide/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/couchbaselabs%2Fdocs-style-guide/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/couchbaselabs%2Fdocs-style-guide/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/couchbaselabs","download_url":"https://codeload.github.com/couchbaselabs/docs-style-guide/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/couchbaselabs%2Fdocs-style-guide/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28727384,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-24T10:24:43.181Z","status":"ssl_error","status_checked_at":"2026-01-24T10:24:36.112Z","response_time":89,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docs","docs-tooling"],"created_at":"2024-12-26T22:29:37.946Z","updated_at":"2026-01-24T12:08:01.255Z","avatar_url":"https://github.com/couchbaselabs.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Couchbase Vale Style Guide\n\nThis repository is the home of the Couchbase Style Guide files - also translated into Vale format! \n\n[Vale](https://vale.sh/) is an open-source text linter that Couchbase uses to help enforce style guidelines, right inside your code editor. \n\n## Get Started \n\nTo get started with the Vale Style guide, you need to: \n\n1. Clone this repository to your computer. \n2. [Install Vale](#install-vale). \n3. [Set up a `.vale.ini` file](#set-up-a-valeini-file).\n4. [Install AsciiDoctor](#install-asciidoctor).\n\n### Install Vale\n\nTo install Vale: \n\n1. If you haven't already, install a package manager: \n    - On Windows: [Chocolatey](https://chocolatey.org/install)\n    - On Mac: [Homebrew](https://brew.sh/)\n    - On GNU/Linux: Don't use the Snap package manager. [Download the precompiled binary of Vale](https://vale.sh/docs/vale-cli/installation/#github-releases).\n\n2. Open a terminal application with administrator permissions. \n\n3. Follow the instructions at [Vale.sh](https://vale.sh/docs/vale-cli/installation/) for your platform. \n\nThe package manager does all of the heavy lifting to install Vale. If you receive a prompt to run additional scripts from your terminal, approve it. \n\n### Set Up A .vale.ini File \n\nThe `.vale.ini` file contains all of the necessary configuration for Vale to lint your text files.\n\nYou'll need to create this file and configure it, to make sure that Vale pulls in the style rules from the correct location on your computer: \n\n1. In your file explorer, go to your `$HOME` directory: \n    - On Windows: `C:\\Users\\\u003cyourusername\u003e`\n    - On Mac: `/Users/\u003cyourusername\u003e`\n    - On Linux: the location of the `$HOME` directory varies based on your specific Linux distribution.\n  \n2. In your `$HOME` directory, create a new plain text file called `.vale.ini`. \n\n3. Open the `.vale.ini` file in a text editor.\n\n4. Copy and paste the following text into the `.vale.ini` file:\n```\nStylesPath = \"\"\nMinAlertLevel = suggestion \n\nVocab = Couchbase\n\n[asciidoctor]\ndescription = YES\ndocname = YES\ndoctitle = YES\ndoctype = YES\ndocfile = YES\nexample-caption = YES\nfigure-caption = YES\nimportant-caption = YES\nlisting-caption = YES\nnote-caption = YES\noutfile = YES\npart-signifier = YES\npreface-title = YES\ntable-caption = YES\ntip-caption = YES\ntoc-title = YES\nwarning-caption = YES\n\nexperimental = YES\n\nattribute-missing = drop\n\n[*.{adoc}]\nBasedOnStyles = Vale, write-good, proselint, Couchbase, Google\n```\n\n5. Inside the quotation marks for the `StylesPath`, enter the location on your computer of the `ValeStyles` folder in this repository. \n    For example, `C:\\Users\\\u003cyourusername\u003e\\GitHub\\docs-style-guide\\ValeStyles` or `/Users/\u003cyourusername\u003e/GitHub/docs-style-guide/ValeStyles`.\n\n### Install AsciiDoctor\n\nYou need to install AsciiDoctor so Vale knows how to interpret the AsciiDoc file format that Couchbase uses to author documentation. \n\nTo use Vale with AsciiDoc on Windows, you need to install Ruby before you can install AsciiDoctor. \n\nFor all other systems, you can just install the AsciiDoctor package on your computer. \n\n#### Windows  \n\n1. In a terminal window, run: \n```\nchoco install ruby\n```\n\n2. Then: \n```\ngem install asciidoctor\n```\n\n#### MacOS \n\n1. In a terminal window, run: \n```\nbrew install asciidoctor\n```\n\n#### GNU/Linux \n\nConsult [the AsciiDoctor Docs](https://asciidoctor.org/#linux-package-managers) for details based on your specific distribution's package manager.\n\n## Lint a File \n\nAfter you've done all the setup, you're ready to lint some files! \n\n1. Open the file or folder's location on your filesystem in a terminal window. \n\n2. Run `vale \u003cFileName\u003e` or `vale \u003cFolderName\u003e`. \n\n\u003e **Tip**: If you want Vale to print to a file that you can review later, add `\u003e \u003coutputFileName\u003e.txt` to the end of your Vale command: \n```\nvale myFolder \u003e valeResults.txt\n```\n\nVale generates a report that provides the following information: \n\n1. If you ran Vale on a folder, the name of the file where Vale found the following list of issues.  \n2. The line number and character/column number where Vale found an issue. \n3. The severity of the issue: Suggestion, Warning, or Error.\n4. The description of why Vale flagged the issue. \n5. The location of the YAML file that flagged the issue, written as `\u003cFolderName\u003e.\u003cFileName\u003e`, based on the contents of `ValeStyles` in this repository. \n\n![A screenshot from Windows Terminal, showing a possible output of running Vale on a file.](vale-report-example.png)\n\nIf you run into issues linting a folder:\n\n- Check your `.vale.ini` to see what file types Vale lints. If you see a [*] above the `BasedOnStyles` setting, Vale lints all file types. Enter a file type (`.adoc`, for example) to change the scope. \n- Change the folder to limit the scope of the files you want Vale to lint. Large numbers of files might not run correctly through Vale.\n\nFor a nicer editing experience, try [linting in real time inside VS Code](#linting-in-real-time).\n\n## Linting in Real Time\n\nYou can also get live feedback as you write from the Vale VSCode extension:\n\n1. Click **Extensions**.  \n![The extensions tab in VSCode](vscode-extensions-tab.png)\n2. Search for **Vale VSCode** (by Chris Chinchilla).\n3. Click **Install**.\n4. Click the gear and go to **Extension Settings**.  \n![The manage extension button in VSCode](manage-button.png)\n5. Click **Enable spell checking with Vale**.\n6. Set **Readability Problem Location** to **both**, or just **inline**.\n7. Restart VS Code, by closing any open editor windows and reopening the application.\n\nIf the extension does not work as expected, you can go back into your Extension Settings for Vale and try the following: \n\n1. In Config, input the path to your .vale.ini:\n    * Mac: `/Users/\u003cyourusername\u003e/.vale.ini`\n    * Windows: `C:\\Users\\\u003cyourusername\u003e\\.vale.ini`\n2. Find the path to the Vale.exe and add it in the Path field:\n    * Mac: `/usr/local/bin/vale`\n    * Windows: `C:\\ProgramData\\chocolatey\\lib\\vale\\tools\\vale.exe`\n  \nOnly make one of these changes at a time to help with troubleshooting. Make sure to restart VS Code in-betweeen any changes. \n\n\u003e **Note**:\nThe Vale VS Code extension only runs and checks for problems when the you save an open file. You can go to **File** and select **Auto Save** to have VSCode automatically save files as you are typing - giving you truly instant feedback on your writing. Be aware that this setting applies globally, and may have side-effects elsewhere.\n\n\n\n## Edit Vale Styles \n\nTo tweak the existing styles in Vale, open any `.yml` file in a text editor and make your changes. \n\nVale uses Go-based RegEx. If you need help to write a RegEx pattern, use a site like [regex101.com](https://regex101.com/) to learn syntax. \nMake sure to actually test any of your rules through [Vale Studio](https://studio.vale.sh/). \nKeep in mind that Vale extends the Go-based RegEx, and supports lookahead and lookbehind patterns.\n\nIf you have a specific term like a page or product name that must be spelled the same and appear the same way everywhere, add it to the **Vocab** files: \n\n1. Go to `ValeStyles\\config\\vocabularies\\Couchbase`. \n2. Do one of the following: \n    - To add a word or phrase that Vale should never flag as incorrect in any other rule, modify the `accept.txt` file. \n    - To add a word or phrase that Vale should always reject that isn't yet covered by another rule, modify the `reject.txt` file. \n\nKeep the following in mind: \n\n- Add only a single word or phrase per line to the `accept.txt` or `reject.txt`. \n- If multiple spellings for your word or phrase are correct, make sure that you add them with RegEx to the `accept.txt`. Otherwise, Vale flags any spellings or capitalization styles that don't exactly match what's present in the file. \n- If your word or phrase includes punctuation or other characters that are a part of RegEx syntax, make sure you escape them with a backslash (\\\\). Otherwise, Vale breaks. \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcouchbaselabs%2Fdocs-style-guide","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcouchbaselabs%2Fdocs-style-guide","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcouchbaselabs%2Fdocs-style-guide/lists"}