add cc to build

.github/workflows/vale-check.yml

@@ -1,20 +1,32 @@
 name: Lint Docs
 
-on: [push, pull_request]
+on:
+  pull_request:
+  push:
+    branches: [main]
 
 jobs:
   lint:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3
       - name: Install Tools
+        env:
+          # Keep in step with the version developers run locally -- older Vale
+          # reports Microsoft.Headings false positives this repo can't reproduce.
+          VALE_VERSION: 3.15.2
         run: |
-          # Install Vale
-          wget https://github.com/errata-ai/vale/releases/download/v3.9.0/vale_3.9.0_Linux_64-bit.tar.gz
-          tar -xvzf vale_3.9.0_Linux_64-bit.tar.gz
-          sudo mv vale /usr/local/bin/
+          # Install Vale. Extract outside the repo: the tarball ships its own
+          # README.md/LICENSE, which otherwise clobber ours and get linted.
+          tmp="$(mktemp -d)"
+          wget -qO "$tmp/vale.tar.gz" \
+            "https://github.com/errata-ai/vale/releases/download/v${VALE_VERSION}/vale_${VALE_VERSION}_Linux_64-bit.tar.gz"
+          tar -xzf "$tmp/vale.tar.gz" -C "$tmp" vale
+          sudo mv "$tmp/vale" /usr/local/bin/
+          vale -v
           # Install Markdownlint
           npm install -g markdownlint-cli
+          markdownlint --version
       - name: Run Quality Check
         run: |
           chmod +x docs-linter/lint.sh

CONTRIBUTING.md

@@ -2,9 +2,9 @@
 
 This guide covers the development workflow for making changes to the NetFoundry Docusaurus theme and shared components.
 
-## Repository Structure
+## Repository structure
 
-```
+```text
 docusaurus-shared/
 ├── packages/
 │   └── docusaurus-theme/     # @netfoundry/docusaurus-theme
@@ -36,30 +36,30 @@ docusaurus-shared/
 └── CONTRIBUTING.md           # You are here
 ```
 
-## The Theme Package
+## The theme package
 
 | Package | npm | Purpose |
 |---------|-----|---------|
 | `@netfoundry/docusaurus-theme` | [npm](https://www.npmjs.com/package/@netfoundry/docusaurus-theme) | Drop-in Docusaurus theme with layout, footer, components, and styling. |
 
 ---
 
-## Development Workflow
+## Development workflow
 
 ### Prerequisites
 
 - Node.js 18+
 - Yarn package manager
 
-### Initial Setup
+### Initial setup
 
 ```bash
 git clone https://github.com/netfoundry/docusaurus-shared.git
 cd docusaurus-shared
 yarn install
 ```
 
-### Quick Commands (from repo root)
+### Quick commands (from repo root)
 
 ```bash
 yarn dev      # Start test-site dev server
@@ -69,9 +69,9 @@ yarn test     # Run theme tests
 
 ---
 
-## Making Changes to the Theme
+## Making changes to the theme
 
-### 1. Configure Local Development
+### 1. Configure local development
 
 The test-site is pre-configured to use the local theme. Check `test-site/docusaurus.config.ts`:
 
@@ -89,7 +89,7 @@ export default {
 };
 ```
 
-### 2. Start Development Server
+### 2. Start development server
 
 ```bash
 yarn dev
@@ -99,7 +99,7 @@ cd test-site && yarn start
 
 Open http://localhost:3000. Changes to theme files hot-reload automatically.
 
-### 3. Make Your Changes
+### 3. Make your changes
 
 Common file locations:
 
@@ -115,7 +115,7 @@ Common file locations:
 | Remark plugins | `packages/docusaurus-theme/src/docusaurus-plugins/` |
 | Theme config types | `packages/docusaurus-theme/src/options.ts` |
 
-### 4. Test Your Changes
+### 4. Test your changes
 
 ```bash
 # Development server (hot reload)
@@ -126,7 +126,7 @@ yarn build
 cd test-site && yarn serve
 ```
 
-### 5. Run Tests
+### 5. Run tests
 
 ```bash
 yarn test
@@ -146,21 +146,24 @@ npm version patch   # 0.1.2 → 0.1.3
 npm publish
 ```
 
-### 7. Verify Published Package
+### 7. Verify published package
 
 Update `test-site/package.json`:
+
 ```json
 "@netfoundry/docusaurus-theme": "^0.1.3"
 ```
 
 Switch `test-site/docusaurus.config.ts` to use package name:
+
 ```typescript
 themes: [
     '@netfoundry/docusaurus-theme',
 ],
 ```
 
 Then:
+
 ```bash
 cd test-site
 yarn install
@@ -169,22 +172,23 @@ yarn build
 
 ---
 
-## Example: Changing a CSS Variable
+## Example: Changing a CSS variable
 
 Here's a complete walkthrough of changing the light-mode tab color.
 
-### The Problem
+### The problem
 
 The tab highlight color (`--nf-tab-color`) is pink in light mode. We want grey instead.
 
-### Step 1: Find the Variable
+### Step 1: Find the variable
 
 ```bash
 grep -n "nf-tab-color" packages/docusaurus-theme/css/legacy.css
 ```
 
 Output:
-```
+
+```text
 89:    --nf-tab-color: 255, 182, 193;
 90:    --nf-tab-color-render: rgb(255, 182, 193);
 143:    --nf-tab-color: 67, 72, 98;
@@ -193,13 +197,13 @@ Output:
 - Line 89-90: Light mode (`:root`)
 - Line 143: Dark mode (`html[data-theme="dark"]`)
 
-### Step 2: Start Dev Server
+### Step 2: Start dev server
 
 ```bash
 yarn dev
 ```
 
-### Step 3: Make the Change
+### Step 3: Make the change
 
 Edit `packages/docusaurus-theme/css/legacy.css` around line 89:
 
@@ -219,11 +223,11 @@ Edit `packages/docusaurus-theme/css/legacy.css` around line 89:
 
 Save. Browser hot-reloads with new color.
 
-### Step 4: Test Dark Mode
+### Step 4: Test dark mode
 
 Toggle dark mode in browser. Dark mode uses a different value (line 143) - verify it still looks correct.
 
-### Step 5: Run Tests & Build
+### Step 5: Run tests & build
 
 ```bash
 yarn test
@@ -238,13 +242,13 @@ npm version patch
 npm publish
 ```
 
-### Step 7: Final Verification
+### Step 7: Final verification
 
 Update `test-site/package.json` to new version, switch config to package name, reinstall, rebuild.
 
 ---
 
-## CSS Variable Reference
+## CSS variable reference
 
 Key variables in `packages/docusaurus-theme/css/legacy.css`:
 
@@ -259,7 +263,7 @@ Key variables in `packages/docusaurus-theme/css/legacy.css`:
 
 ---
 
-## Testing Checklist
+## Testing checklist
 
 Before publishing:
 
@@ -288,23 +292,23 @@ Also verify `docusaurus.config.ts` uses local path, not package name.
 
 ### Module not found?
 
-1. Run `yarn install` from repo root
-2. Check the file exists at the path specified in `package.json` exports
-3. Restart dev server
+1.  Run `yarn install` from repo root
+2.  Check the file exists at the path specified in `package.json` exports
+3.  Restart dev server
 
 ### CSS not loading?
 
-1. Check `css/theme.css` imports the file you changed
-2. Verify `src/index.ts` `getClientModules()` includes `theme.css`
-3. Hard refresh browser (Ctrl+Shift+R)
+1.  Check `css/theme.css` imports the file you changed
+2.  Verify `src/index.ts` `getClientModules()` includes `theme.css`
+3.  Hard refresh browser (Ctrl+Shift+R)
 
 ### TypeScript errors in consuming project?
 
 The theme ships source files. Fix errors in theme source, not consumers.
 
 ---
 
-## Package Entry Points
+## Package entry points
 
 The theme exposes multiple entry points:
 

README.md

@@ -2,9 +2,9 @@
 
 Shared documentation theme, components, and tooling for NetFoundry's Docusaurus-based documentation sites.
 
-## Repository Structure
+## Repository structure
 
-```
+```text
 docusaurus-shared/
 ├── packages/
 │   ├── docusaurus-theme/     # @netfoundry/docusaurus-theme npm package
@@ -17,9 +17,9 @@ docusaurus-shared/
 See [`packages/test-site/README.md`](./packages/test-site/README.md) for the
 test-site dev loop, docs organization, and debug recipes.
 
-## Quick Start
+## Quick start
 
-### Using the Theme
+### Using the theme
 
 Install the theme in your Docusaurus project:
 
@@ -52,7 +52,7 @@ export default {
 
 See the [theme README](./packages/docusaurus-theme/README.md) for full documentation.
 
-### Creating a New Doc Site
+### Creating a new doc site
 
 ```bash
 ./bootstrap.sh /path/to/new-site [starLabel] [starRepoUrl]
@@ -88,17 +88,17 @@ See [packages/test-site/README.md](./packages/test-site/README.md) for the full
 dev-loop walkthrough, debug recipes, and what hot-reloads vs. what needs a
 rebuild.
 
-## Local Development
+## Local development
 
 See [packages/LOCAL-DEV.md](./packages/LOCAL-DEV.md) for the full local development guide, including how to use the test-site, test with remote sites via `file:` protocol, and publish.
 
 ## Contributing
 
 See [CONTRIBUTING.md](./CONTRIBUTING.md) for development setup, workflow, and a walkthrough example of making theme changes.
 
-## Best Practices
+## Best practices
 
-### Relative Linking
+### Relative linking
 
 Use relative paths for internal links:
 
@@ -115,7 +115,7 @@ Here [is a link](/docs/to/some/path.md)
 
 Add images to the static folder scoped to your site:
 
-```
+```text
 /your-doc-site/static/img/your-doc-site/
 ```
 
@@ -131,11 +131,11 @@ import SharedContent from '../_shared.content.md'
 <SharedContent />
 ```
 
-## Kinsta Hosting
+## Kinsta hosting
 
 The docusaurus site is hosted on Kinsta. Required nginx rule:
 
-```
+```nginx
 location /docs/ {
   try_files $uri $uri/ $uri/index.html /docs/index.html;
 }

docs-linter/.markdownlint.json

@@ -5,6 +5,10 @@
   "MD033": false, // Inline HTML. Essential for Docusaurus features (tabs, admonitions, specialized formatting).
   "MD034": false, // Bare URLs (e.g. https://example.com) without <brackets>. Common in quickstart guides.
   "MD009": false, // Trailing spaces. Flags every invisible space at the end of a line. Huge noise source.
+  "MD010": { "code_blocks": false }, // Hard tabs. Allowed inside code blocks -- Go, Makefiles use real tabs.
+  "MD025": { "front_matter_title": "" }, // Don't count frontmatter title as an H1; Docusaurus docs use frontmatter title + one body H1.
+  "MD028": false, // Blank line between consecutive blockquotes -- legit for stacked GitHub-style admonitions.
+  "MD030": { "ol_single": 2, "ol_multi": 2 }, // Ordered lists use 2 spaces after the marker (4-space content indent, per nf-style-guide).
   "MD060": false, // Table column style. Flags tables that aren't perfectly ASCII-aligned in the raw text file. Purely visual.
   "MD041": false  // First line heading. Fires on every Docusaurus category index page (MDX imports before any heading).
 }

docs-linter/.vale.ini

@@ -17,3 +17,6 @@ Microsoft.Contractions = NO
 Microsoft.FirstPerson = NO
 Microsoft.HeadingPunctuation = NO
 Microsoft.Dashes = NO
+Microsoft.Auto = NO
+Microsoft.Spacing = NO
+Microsoft.Ellipses = NO