How to Use Arc-Kit for Frontend Development: Building Static Documentation Sites

Arc-kit generates a GOV.UK-styled, responsive static documentation site via the arckit pages command, which processes pages-template.html and renders architecture artifacts with Mermaid and PlantUML support without requiring a backend.

Arc-kit is an enterprise-architecture governance toolkit that includes a full-stack frontend for publishing architecture artifacts. When you use arc-kit for frontend development, you generate static documentation sites that leverage the GOV.UK Frontend design system and client-side diagram rendering to create zero-cost, self-hosted documentation.

Prerequisites and Initial Setup

Before generating the frontend, initialize a new arc-kit project with your preferred AI target. The initialization creates the necessary directory structure and metadata files.

# Initialize with Claude as the AI target (supports claude, opencode, codex, etc.)

arckit init my-frontend-project --ai claude

This command creates the projects/ hierarchy and establishes the foundation for the documentation site. The frontend generation process relies on this structure to locate and process architecture artifacts.

Generating the Static Site with arckit pages

The core command for arc-kit frontend development is arckit pages. This command orchestrates the entire build process through the sync-guides hook.

# Generate the documentation site (creates docs/ folder)

arckit pages

The command executes the following workflow as defined in arckit-claude/commands/pages.md:

1. Runs the sync-guides hook (arckit-claude/hooks/sync-guides.mjs) to gather guide files and repository metadata
2. Processes pages-template.html and injects the collected data
3. Writes docs/index.html, docs/manifest.json, and docs/llms.txt

The resulting docs/ folder contains a completely static site that can be served on any static host including GitHub Pages, Netlify, Vercel, or S3.

Understanding the Frontend Architecture

The Template System (pages-template.html)

The frontend is built around a single-page HTML application defined in arckit-claude/templates/pages-template.html. This template uses the GOV.UK Frontend design system for accessible UI components and responsive layouts.

The template supports:

• Dark-mode toggling via client-side JavaScript
• Responsive grid layouts that work on mobile and desktop
• Version badges for multi-version documents

When you run arckit pages, the sync-guides hook processes this template and injects the manifest.json data directly into the HTML.

Client-Side Diagram Rendering

Arc-kit frontend development includes built-in support for architecture diagrams without requiring server-side processing:

• Mermaid diagrams: Rendered client-side using the Mermaid JavaScript library
• PlantUML diagrams: Processed through client-side integration

These diagram types are embedded in markdown files using standard code block syntax (```mermaid or ```plantuml), and the template automatically initializes the rendering engines when the page loads.

Version Badge Logic

The template includes sophisticated version handling through the extractVersion and baseDocId functions (located around lines 350-380 in pages-template.html). These functions:

• Extract version identifiers from document IDs
• Display version badges dynamically based on the document metadata
• Support multi-version documentation where users can switch between versions

This logic reads from the manifest.json structure generated by the sync-guides hook.

Customizing the Frontend

To customize the appearance or functionality of your arc-kit documentation site, override the default template:

# Create the override directory structure

mkdir -p .arckit/templates

# Copy the default template to your project

cp $(arckit get-data-paths | grep pages-template.html) .arckit/templates/pages-template.html

# Edit the template

code .arckit/templates/pages-template.html

You can modify:

• CSS variables: Change colors, fonts, and spacing in the <style> block
• JavaScript modules: Add custom functionality before the closing </body> tag
• HTML structure: Rearrange components or add new sections

After editing, run arckit pages again to regenerate the site with your customizations.

Adding Custom Diagram Types

To extend arc-kit frontend development with additional diagram renderers:

1. Add a new <script> tag in your custom pages-template.html to load the renderer (e.g., Graphviz via CDN)
2. Define a CSS class for styling the new diagram type
3. Use the new code block syntax in your markdown files (```graphviz)
4. Regenerate the site with arckit pages

The template loads diagrams lazily, ensuring minimal performance impact.

Deployment Options

The static output in the docs/ folder is compatible with any static hosting platform:

GitHub Pages (Recommended)

1. Push your repository to GitHub
2. Navigate to Settings → Pages
3. Select "Deploy from a branch"
4. Choose the main branch and /docs folder
5. Save and visit https://<owner>.github.io/<repo>/

Netlify or Vercel Drag and drop the docs/ folder into the deployment interface, or connect your Git repository for continuous deployment.

AWS S3 or other object storage Upload the contents of docs/ to your S3 bucket with static website hosting enabled.

The frontend requires no server-side processing, making it ideal for JAMstack architectures and edge deployment.

Summary

Using arc-kit for frontend development enables you to generate professional, accessible documentation sites without writing backend code:

• Initialize projects with arckit init to establish the required structure
• Generate static sites using arckit pages, which processes arckit-claude/templates/pages-template.html through the sync-guides hook
• Customize the frontend by overriding templates in .arckit/templates/pages-template.html and modifying CSS or JavaScript
• Deploy the resulting docs/ folder to any static host including GitHub Pages, Netlify, or S3
• Extend functionality with custom diagram types like Graphviz by adding scripts to your template

The architecture leverages client-side rendering for Mermaid and PlantUML diagrams, version badge logic via extractVersion and baseDocId functions, and the GOV.UK Frontend design system for accessibility compliance.

Frequently Asked Questions

What design system does arc-kit use for its frontend?

Arc-kit uses the GOV.UK Frontend design system for all UI components. This provides accessible, responsive layouts that meet WCAG standards. The CSS and components are embedded in arckit-claude/templates/pages-template.html and can be customized by overriding the template in your project's .arckit/templates/ directory.

Can I use arc-kit for frontend development without a backend server?

Yes. Arc-kit generates a completely static frontend that requires no backend server. The arckit pages command creates a docs/ folder containing index.html, manifest.json, and llms.txt. The site uses client-side JavaScript to load data from manifest.json and render diagrams, making it compatible with GitHub Pages, Netlify, Vercel, or any static file server.

How do I add custom styling or JavaScript to my arc-kit documentation site?

To customize the frontend, copy the default template to your project directory and modify it. Run mkdir -p .arckit/templates and copy arckit-claude/templates/pages-template.html to .arckit/templates/pages-template.html. You can then edit CSS variables in the <style> block or add JavaScript modules before the closing </body> tag. Run arckit pages again to regenerate the site with your changes.

What diagram formats are supported in arc-kit's frontend?

Arc-kit supports Mermaid and PlantUML diagrams out of the box, rendered client-side using JavaScript libraries embedded in pages-template.html. You can extend support for additional formats like Graphviz by loading the appropriate CDN scripts in your custom template and using the corresponding code block syntax in your markdown files.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}