feat: Add Vale documentation linting

.github/workflows/lint-docs.yml

@@ -0,0 +1,28 @@
+name: Lint Documentation
+
+on:
+  pull_request:
+    paths:
+      - 'docs/**'
+      - '*_versioned_docs/**'
+      - 'README.md'
+      - '.vale.ini'
+      - 'styles/**'
+
+jobs:
+  vale:
+    name: Vale
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Vale Linter
+        uses: errata-ai/vale-action@reviewdog
+        with:
+          files: docs
+          fail_on_error: true
+          filter_mode: added
+          reporter: github-pr-review
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -22,3 +22,7 @@ yarn-error.log*
 # VSCode Settings
 .vscode
 .history/
+
+# Vale packages (downloaded by `vale sync`)
+styles/Google/
+styles/write-good/

.vale.ini

@@ -0,0 +1,29 @@
+# Vale configuration for Source Network documentation site
+# Documentation linter based on brand guidelines
+StylesPath = styles
+MinAlertLevel = suggestion
+Packages = Google, write-good
+Vocab = DefraDB
+
+[*]
+BasedOnStyles = Vale, Google, write-good, DefraDB
+# Disable Vale.Terms - we use custom DefraDB.ProductNames and DefraDB.TechTerms instead
+Vale.Terms = NO
+
+[*.{md,mdx}]
+BasedOnStyles = Vale, Google, write-good, DefraDB
+Vale.Terms = NO
+
+# CLI reference docs - relax some rules
+[docs/defradb/references/cli/*.md]
+Google.Headings = suggestion
+DefraDB.Hedging = suggestion
+
+# Release notes - allow different voice
+[docs/*/release?notes/*.md]
+DefraDB.Voice = NO
+DefraDB.CorporateSpeak = suggestion
+
+# Versioned docs - same rules as main docs
+[*_versioned_docs/**/*.{md,mdx}]
+BasedOnStyles = Vale, Google, write-good, DefraDB

Makefile

@@ -1,4 +1,4 @@
-.PHONY: version\:replace help
+.PHONY: version\:replace help lint\:docs lint\:docs\:strict vale\:sync deps\:lint-docs
 
 # Color codes for output
 RED := \033[0;31m
@@ -11,20 +11,23 @@ NC := \033[0m # No Color
 VALID_PROJECTS := defradb sourcehub orbis lensvm
 
 help:
-	@echo "$(BLUE)Docusaurus Version Management$(NC)"
+	@echo "$(BLUE)Source Network Documentation Tools$(NC)"
 	@echo ""
-	@echo "$(GREEN)Available commands:$(NC)"
+	@echo "$(GREEN)Version Management:$(NC)"
 	@echo "  make version:replace PROJECT=<project> VERSION=<version>"
+	@echo "    Regenerates and replaces Docusaurus versioned docs for a specific version"
+	@echo "    PROJECT: defradb, sourcehub, orbis, lensvm"
+	@echo "    VERSION: must exist in <project>_versions.json"
 	@echo ""
-	@echo "$(GREEN)Description:$(NC)"
-	@echo "  Regenerates and replaces Docusaurus versioned docs for a specific version"
+	@echo "$(GREEN)Documentation Linting:$(NC)"
+	@echo "  make deps:lint-docs    - Install Vale documentation linter"
+	@echo "  make vale:sync         - Sync Vale style packages"
+	@echo "  make lint:docs         - Run Vale on all documentation (all levels)"
+	@echo "  make lint:docs:strict  - Run Vale (errors only)"
 	@echo ""
-	@echo "$(GREEN)Arguments:$(NC)"
-	@echo "  PROJECT  - Project name (defradb, sourcehub, orbis, lensvm)"
-	@echo "  VERSION  - Version identifier (must exist in <project>_versions.json)"
-	@echo ""
-	@echo "$(GREEN)Example:$(NC)"
+	@echo "$(GREEN)Examples:$(NC)"
 	@echo "  make version:replace PROJECT=defradb VERSION=0.19.0"
+	@echo "  make lint:docs"
 	@echo ""
 
 version\:replace:
@@ -145,3 +148,35 @@ version\:replace:
 	@echo "  2. Test the docs locally with: npm run start"
 	@echo "  3. Commit the changes when satisfied"
 	@echo ""
+
+# ============================================================================
+# Vale Documentation Linting
+# ============================================================================
+
+deps\:lint-docs:
+	@echo "$(BLUE)Installing Vale documentation linter...$(NC)"
+	@if command -v vale >/dev/null 2>&1; then \
+		echo "$(GREEN)✓ Vale is already installed$(NC)"; \
+		vale --version; \
+	else \
+		echo "$(YELLOW)Installing Vale via Homebrew...$(NC)"; \
+		brew install vale; \
+	fi
+
+vale\:sync:
+	@echo "$(BLUE)Syncing Vale style packages...$(NC)"
+	@vale sync
+	@echo "$(GREEN)✓ Vale packages synced$(NC)"
+
+lint\:docs: vale\:sync
+	@echo "$(BLUE)Running Vale documentation linter...$(NC)"
+	@echo ""
+	@vale --minAlertLevel=suggestion docs README.md || true
+	@echo ""
+	@echo "$(GREEN)Linting complete.$(NC)"
+	@echo "$(YELLOW)Note: Run 'make lint:docs:strict' to see only errors.$(NC)"
+
+lint\:docs\:strict: vale\:sync
+	@echo "$(BLUE)Running Vale documentation linter (errors only)...$(NC)"
+	@echo ""
+	@vale --minAlertLevel=error docs README.md

README.md

@@ -19,12 +19,12 @@ Most changes are reflected live without having to restart the server.
 
 This website is built using [Docusaurus 2](https://docusaurus.io/).
 
-Documentation is written using [common markdown syntax](https://commonmark.org/help/) or [MDX syntax](https://mdxjs.com/docs/what-is-mdx/#mdx-syntax) - the file extension will determine the syntax (.md for common markdown and .mdx for MDX).
+Documentation is written using [common markdown syntax](https://commonmark.org/help/) or [MDX syntax](https://mdxjs.com/docs/what-is-mdx/#mdx-syntax). Use `.md` files for common markdown and `.mdx` files for MDX.
 
 ## Deployment
 
-The website is automatically deployed using Cloudfare Pages.
+The website is automatically deployed using Cloudflare Pages.
 
 ## Contributing
 
-Feedback and pull requests appreciated!
+Feedback and pull requests appreciated.

styles/DefraDB/Acronyms.yml

@@ -0,0 +1,46 @@
+extends: conditional
+message: "Define acronym '%s' on first use in this document"
+level: warning
+link: https://docs.source.network
+scope: text
+ignorecase: true
+first: '\b([A-Z]{2,})\b'
+second: '(?:[A-Z][a-z][\w\-]+ )+\(([A-Z]{2,})\)'
+exceptions:
+  # Common acronyms that don't need definition
+  - API
+  - CLI
+  - HTTP
+  - HTTPS
+  - JSON
+  - REST
+  - SQL
+  - URL
+  - UI
+  - UX
+  - ID
+  - SDK
+  - TLS
+  - SSL
+  - TCP
+  - UDP
+  - IP
+  - DNS
+  - SSH
+  - CPU
+  - RAM
+  - I/O
+  - OS
+
+  # DefraDB-specific acronyms
+  - CRUD
+  - CORS
+  - P2P
+  - IoT
+  - NAT
+  - DHT
+  - RPC
+  - AMI
+  - DSL
+  - ACP
+  - DQL

styles/DefraDB/CorporateSpeak.yml

@@ -0,0 +1,29 @@
+extends: existence
+message: "Avoid corporate buzzword '%s' - be specific and direct instead"
+level: warning
+link: https://docs.source.network
+ignorecase: true
+scope: text
+tokens:
+  # Corporate buzzwords from brand guidelines
+  - leverage
+  - leveraging
+  - synergy
+  - synergistic
+  - synergies
+  - cutting-edge
+  - revolutionary
+  - revolutionize
+  - unparalleled
+  - best-in-class
+  - world-class
+  - paradigm shift
+  - next-generation
+  - enterprise-grade
+  - mission-critical
+  - turnkey
+  - seamlessly
+  - holistic
+  - robust solution
+  - comprehensive solution
+  - end-to-end solution

styles/DefraDB/GrandioseClaims.yml

@@ -0,0 +1,22 @@
+extends: existence
+message: "Avoid unsupported claim '%s' - provide specific evidence or proof instead"
+level: warning
+link: https://docs.source.network
+ignorecase: true
+scope: text
+nonword: true
+tokens:
+  - the best
+  - the leading
+  - the most secure
+  - the fastest
+  - the only
+  - the ultimate
+  - the perfect
+  - the ideal
+  - industry-leading
+  - market-leading
+  - award-winning
+  - groundbreaking
+  - 'number one'
+  - '#1'

styles/DefraDB/Headings.yml

@@ -0,0 +1,49 @@
+extends: capitalization
+message: "Headings should use title case: '%s'"
+level: suggestion
+link: https://docs.source.network
+scope: heading
+match: $title
+style: AP
+exceptions:
+  # Product names
+  - DefraDB
+  - SourceHub
+  - Orbis
+  - LensVM
+
+  # Technology names
+  - MongoDB
+  - PostgreSQL
+  - GraphQL
+  - IPFS
+  - libp2p
+  - WebAssembly
+
+  # Terms with specific casing
+  - edge-first
+  - local-first
+  - open source
+  - open web
+  - iOS
+  - macOS
+  - JavaScript
+  - TypeScript
+
+  # Acronyms
+  - API
+  - CLI
+  - SDK
+  - HTTP
+  - JSON
+  - REST
+  - SQL
+  - CRUD
+  - CORS
+  - P2P
+  - IoT
+  - ACP
+  - DQL
+  - CRDT
+  - DAG
+  - CID

styles/DefraDB/Hedging.yml

@@ -0,0 +1,32 @@
+extends: existence
+message: "Remove hedging word '%s' - be direct and confident"
+level: suggestion
+link: https://docs.source.network
+ignorecase: true
+scope: text
+tokens:
+  # Weak qualifiers that undermine technical writing
+  - simply
+  - just
+  - easily
+  - easy
+  - obviously
+  - clearly
+  - basically
+  - actually
+  - really
+  - very
+  - quite
+  - rather
+  - somewhat
+  - fairly
+  - kind of
+  - sort of
+exceptions:
+  # Allow "just" in time contexts
+  - just released
+  - just shipped
+  - just launched
+  # Allow "simply" in specific technical contexts
+  - simply put
+  - put simply

styles/DefraDB/NoteFormat.yml

@@ -0,0 +1,17 @@
+extends: existence
+message: "Use standard note format: '**Note:** text' instead of '%s'"
+level: suggestion
+link: https://docs.source.network
+ignorecase: false
+scope: text
+nonword: true
+tokens:
+  - 'Note:'
+  - 'NOTE:'
+  - '\*Note\*:'
+  - '\*NOTE\*:'
+raw:
+  - '^Note: '
+  - '^NOTE: '
+  - '^\*Note\*: '
+  - '^\*NOTE\*: '

styles/DefraDB/PreferredTerms.yml

@@ -0,0 +1,23 @@
+extends: substitution
+message: "Consider using '%s' instead of '%s' for brand consistency"
+level: suggestion
+link: https://docs.source.network
+ignorecase: true
+swap:
+  # Preferred brand terminology from guidelines
+  blockchain: trust protocol|trust layer
+  whitelist: allow list
+  blacklist: deny list
+  master: primary|main
+  slave: replica|secondary
+
+  # Database terminology
+  db: database
+  NoSQL: NoSQL database
+
+  # Simplification
+  utilize: use
+  utilizes: uses
+  utilization: use
+  facilitate: help|enable
+  facilitates: helps|enables