Style Guides & Linting (Vale)
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
Style guides and linting within the CircleCI Docs project ensure that all technical documentation maintains a high standard of clarity, accuracy, and consistency. This system is primarily focused on enforcing semantic guidelines for AsciiDoc content and code quality for the underlying technical infrastructure. The project leverages automated validation tools to provide immediate feedback to contributors during the authoring process.
The scope of linting covers both the prose (using semantic guidelines and writing styles) and the technical codebase (using ESLint for JavaScript and Prettier for formatting). These checks are integrated into the contribution workflow to prevent common errors, such as broken cross-references or improper heading hierarchies, from reaching production.
Sources: CONTENT_AUTHORING.md:1-10, CONTRIBUTING.md:100-110, ARCHITECTURE.md:15-25
Linting Architecture & Components
The linting system is divided into content validation for AsciiDoc and code linting for the site's technical components. The architecture ensures that every contribution undergoes both automated and manual review stages.
Content Validation (Prose & AsciiDoc)
The project utilizes semantic guidelines to govern how documentation is written. This includes enforcing active voice, present tense, and direct address ("you"). Technical authors are required to validate document structures, such as ensuring proper heading levels (Level 0 through Level 4) and verifying that all internal cross-references (xref:) resolve correctly.
Sources: CONTENT_AUTHORING.md:180-200, DEVELOPMENT.md:150-160
Technical Linting (JavaScript & CSS)
The infrastructure codebase uses standard linting tools to maintain code quality:
- ESLint: Enforces JavaScript coding standards and best practices defined in the project configuration.
- Prettier: Handles consistent code formatting across the repository.
- TailwindCSS: Used for CSS linting through utility-class conventions.
Sources: CONTRIBUTING.md:115-130, DEVELOPMENT.md:45-55, package.json:20-35
Automated Validation Flow
The following diagram illustrates the workflow a contribution takes from local development through the linting and review pipeline.
The workflow ensures that automated checks (CI) and manual reviews (Peer/Editorial) act as gates for quality.
Sources: CONTRIBUTING.md:175-195, CONTENT_AUTHORING.md:215-235
Style & Semantic Guidelines
The documentation follows a specific set of semantic rules to ensure readability for developers.
Writing Style Requirements
- Voice: Active voice is mandatory; avoid passive constructions.
- Tense: Use present tense whenever possible.
- Perspective: Address the reader directly as "you."
- Structure: Documentation must be categorized as Tutorials, How-to Guides, Technical Reference, or Explanations.
Sources: CONTENT_AUTHORING.md:180-195
Formatting & Syntax Standards
Consistency in formatting is enforced for UI elements and technical snippets.
| Category | Requirement | Source |
|---|---|---|
| Headings | Must be hierarchical (= to ====); do not skip levels. | CONTENT_AUTHORING.md:120-125 |
| Code Blocks | Must include syntax highlighting (e.g., [source,yaml]). | CONTENT_AUTHORING.md:130-140 |
| Line Length | JavaScript files are limited to 100 characters per line. | CONTRIBUTING.md:118 |
| Media | Images must reside in assets/images/ and include Alt Text. | CONTENT_AUTHORING.md:170-175 |
| JS Documentation | Functions must be documented using JSDoc comments. | CONTRIBUTING.md:117 |
Linting Integration in Development
Linting is integrated into the project's package.json scripts and the developer's local environment.
Developer Tooling
Developers are encouraged to configure their editors with specific extensions to catch errors in real-time:
- ESLint Extension: For JavaScript linting.
- Prettier: For automated formatting.
- AsciiDoc Extension: For live preview and syntax checking of
.adocfiles.
Sources: DEVELOPMENT.md:45-55
Validation Scripts
The project provides scripts for validating various parts of the system:
# Run local development server with live reload and warnings
npm run start:dev
# Validate HTML and check for broken internal links
npm run htmlproofer:dev
Sources: package.json:5-15, TECHNICAL_REFERENCE.md:100-110
Review Checklist
Before content is merged, it is measured against a "Self-Review Checklist" which serves as a manual linting phase.
- Structure: Does the document follow H1-H4 hierarchy?
- Cross-references: Do all
xref:links resolve to valid pages or components? - Code: Are examples tested and formatted correctly in
[source]blocks? - Navigation: Are entries in
nav.adoccorrectly formatted and placed? - Metadata: Are
:description:and:page-toclevels:defined?
Sources: CONTENT_AUTHORING.md:215-230, ARCHITECTURE.md:70-80
Summary
Style guides and linting in the CircleCI Docs project are not merely suggestions but are enforced through a combination of automated tooling (ESLint, Prettier, CI) and rigorous manual review checklists. By standardizing the writing style (active voice, present tense) and technical formatting, the project ensures that documentation is as maintainable and reliable as the code it describes.