Linter

The Linter enforces your style guide automatically as you edit. You write rules in natural language — like "Use active voice" or "Flag placeholder text" — and it checks every page against them, catching inconsistencies that would otherwise ship. Issues show up in the editor grouped into style guide ratings, errors, and warnings. Click any issue to fix it manually, or click Fix All to resolve it in place. Broken links are caught automatically without any rule configuration.

Getting Started

1. Open AI → Linter in your project.
2. Add at least one rule (see Configure below).
3. Open any page in the editor and click the Linter icon in the toolbar to run it.

Configure

Add rules as natural-language prompts. Each rule tells the Linter what to check for.

Style Guide rules

Define what good documentation looks like. The Linter scores content against these.

Keep it short

Short text is always better. Short paragraphs are easier to read. Try to keep headings to one line. Two-line headings take up twice as much vertical space. Use short words in headings; if a customer uses larger fonts to improve accessibility, long words may break across lines.

Clarity

Clear and concise text for easy scanning and readability. Get to the point so users can easily find what they need. Don't use excessive words.

Natural and human tone

Use everyday words that are easy to understand. Less formal but more professional than everyday conversation. Occasionally use a fun tone for celebratory moments but never for informational text. Be warm and supportive to users reading the docs.

Error rules

Objective issues that can be checked without judgment.

Capitalize ReadMe properly

Bad: Readme
Good: ReadMe

Wrap code elements in backticks

Bad: Run npm install -g my-package
Good: Run npm install -g my-package

Flag placeholder text like TODO, FIXME, or Lorem ipsum

Example: TODO: Add description and image to this feature

Warning rules

Subjective issues that may need editorial judgment.

Hedging language

Avoid uncertain or overly cautious language. It undermines confidence and makes instructions less direct.

Bad: You might want to consider installing the latest version.
Good: Install the latest version to access new features.

Weak writing

Avoid 'You can' or 'There is'. These phrases bury the action and add unnecessary words.

Bad: You can configure the API by editing the settings file.
Good: Configure the API by editing the settings file.

Active voice

Active voice is clearer and tells the reader exactly who does what.

Bad: The token is generated when the user logs in.
Good: The system generates a token when the user logs in.

Example

You're editing your "Authentication" guide and run the Linter. It returns:

• Style Guide — "Heading 'How To Set Up OAuth 2.0 Authentication For Your Application' is too long. Keep headings to one line." Score: 74%.
• Error — "Line 12: 'Readme' should be 'ReadMe'."
• Error — "Line 45: Broken link to /docs/api-keys (page not found)."
• Warning — "Line 23: 'You might want to consider using a refresh token' — hedging language. Try: 'Use a refresh token to maintain access without re-authenticating.'"

You fix the product name and broken link manually. For the heading and the hedging language, you click Fix with Agent — the Agent shortens the heading and rewrites the sentence in one pass. Run the Linter again: all issues resolved, score now 96%.

FAQ