This guide explains how to build and serve the ARX documentation site locally.

Requirements

• Node.js 14+
• npm

Start Here

Before building, make sure the docs entry points are current:

• Documentation Home
• Documentation Guide
• Table of Contents

Quick Start

Build HTML Documentation

From the project root:

``bash node build-docs.js ``

This will:

1. Parse all Markdown files from docs/
2. Convert to HTML with syntax highlighting
3. Generate a complete static HTML site
4. Output to docs/_build/html/

Serve Documentation Locally

``bash node serve-docs.js ``

Then open http://localhost:8080 in your browser.

To use a different port:

``bash PORT=3000 node serve-docs.js ``

Project Structure

`` docs/ ├── index.md # Documentation home page ├── README.md # Documentation guide ├── SUMMARY.md # GitBook table of contents ├── book.json # GitBook configuration ├── build-docs.js # Build script (in root) ├── serve-docs.js # Server script (in root) ├── styles/ │ └── website.css # Custom CSS styles │ ├── getting-started/ # Introductory guides ├── sdk/ # Python SDK documentation ├── api/ # REST API reference ├── governance/ # Governance and policy docs ├── admin/ # Administration guides ├── connectors/ # Connector integration guides ├── compliance/ # Compliance documentation ├── _build/ │ └── html/ # Generated static HTML (not in git) │ └── _nav.yaml # Original navigation structure (legacy) ``

Generated Output

The build process generates:

• 68 static HTML files covering all documentation
• 1.3 MB total size (uncompressed)
• Responsive design that works on mobile and desktop
• Dark mode support (respects system preferences)
• Syntax highlighting for code examples
• Table of contents for easy navigation
• Full-text searchable content

Output structure:

`` docs/_build/html/ ├── index.html # Home page ├── api/ │ ├── agents.html │ ├── policies.html │ ├── saml.html │ ├── scim.html │ ├── sso.html │ └── ... ├── getting-started/ │ ├── what-is-arx.html │ ├── quickstart.html │ └── ... ├── sdk/ │ ├── client-reference.html │ ├── error-handling.html │ └── ... ├── governance/ ├── admin/ ├── connectors/ ├── compliance/ └── ... ``

Building with npm Scripts

Add these scripts to package.json:

``json { "scripts": { "docs:build": "node build-docs.js", "docs:serve": "node serve-docs.js", "docs:dev": "npm run docs:build && npm run docs:serve" } } ``

Then run:

```bash

Build

npm run docs:build

Serve

npm run docs:serve

Build and serve

npm run docs:dev ```

Customization

Styling

Edit docs/styles/website.css to customize colors, fonts, and layout.

Key theme variables:

``css :root { --color-primary: #2563eb; /* Blue */ --color-primary-dark: #1e40af; /* Dark blue */ --color-bg: #ffffff; /* Background */ --color-text: #1f2937; /* Text */ --color-border: #e5e7eb; /* Border */ --color-success: #10b981; /* Green */ --color-warning: #f59e0b; /* Orange */ --color-danger: #ef4444; /* Red */ } ``

Navigation Structure

Edit docs/SUMMARY.md to change the table of contents:

```markdown

Section Name

* What is AI Workforce Infrastructure? * What is ARX? ```

Build Script Options

The build script (build-docs.js) automatically:

• Detects all .md files from SUMMARY.md
• Converts Markdown to HTML using marked
• Applies syntax highlighting with highlight.js
• Generates responsive HTML with embedded CSS
• Creates navigation sidebar
• Generates index.html from README.md

Publishing

Deploy to GitHub Pages

```bash

Build

npm run docs:build

Create gh-pages branch if needed

git checkout --orphan gh-pages

Push output to gh-pages

git add docs/_build/html git commit -m "Update documentation" git push origin gh-pages ```

Then configure GitHub Pages to serve from gh-pages branch.

Deploy to Vercel

```bash

Install Vercel CLI

npm install -g vercel

Deploy

vercel docs/_build/html ```

Deploy to Netlify

```bash

Install Netlify CLI

npm install -g netlify-cli

Deploy

netlify deploy --prod --dir docs/_build/html ```

Deploy to Static Hosting

Copy the contents of docs/_build/html/ to:

• AWS S3 + CloudFront
• Google Cloud Storage
• Azure Storage
• Any static hosting service

Development Workflow

1. Edit Markdown files in docs/
2. Run build: npm run docs:build
3. View changes: Open docs/_build/html/index.html in browser
4. Iterate: Make changes and rebuild

For live reloading during development:

```bash npm install -g chokidar-cli

Watch docs and rebuild on changes

chokidar "docs/**/*.md" -c "npm run docs:build" ```

Troubleshooting

Build fails with "Module not found"

Install dependencies:

``bash npm install marked highlight.js ``

Server won't start on port 8080

Port might be in use. Use a different port:

``bash PORT=3000 node serve-docs.js ``

CSS not loading

Check that styles are embedded in HTML. The build script embeds CSS directly in each HTML file, so styles should always be available.

Navigation links broken

Ensure SUMMARY.md has correct file paths. Paths should be relative to docs/ directory.

Tips

1. Keep Markdown clean: Use consistent formatting for headers, lists, and code blocks
2. Use relative links: Links within docs should use .md format (will be converted to .html)
3. Add descriptions: Use frontmatter in Markdown for metadata:

``yaml --- title: Page Title description: Short description for SEO --- ``

1. Test locally: Always build and test locally before publishing
2. Check for broken links: The build script will warn about missing files

Support

• Documentation: Read the generated HTML docs
• Issues: Report build issues at https://github.com/gethammerpath/project-agent/issues
• Feedback: Suggestions welcome!