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

> Learn how to use Arc-Kit for frontend development to build GOV.UK-styled static documentation sites. Effortlessly render architecture artifacts with Mermaid and PlantUML support.

- Repository: [tractorjuice/arc-kit](https://github.com/tractorjuice/arc-kit)
- Tags: how-to-guide
- Published: 2026-04-19

---

**Arc-kit generates a GOV.UK-styled, responsive static documentation site via the `arckit pages` command, which processes [`pages-template.html`](https://github.com/tractorjuice/arc-kit/blob/main/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.

```bash

# 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.

```bash

# Generate the documentation site (creates docs/ folder)

arckit pages

```

The command executes the following workflow as defined in [`arckit-claude/commands/pages.md`](https://github.com/tractorjuice/arc-kit/blob/main/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`](https://github.com/tractorjuice/arc-kit/blob/main/pages-template.html) and injects the collected data
3. Writes [`docs/index.html`](https://github.com/tractorjuice/arc-kit/blob/main/docs/index.html), [`docs/manifest.json`](https://github.com/tractorjuice/arc-kit/blob/main/docs/manifest.json), and [`docs/llms.txt`](https://github.com/tractorjuice/arc-kit/blob/main/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`](https://github.com/tractorjuice/arc-kit/blob/main/pages-template.html))

The frontend is built around a single-page HTML application defined in [`arckit-claude/templates/pages-template.html`](https://github.com/tractorjuice/arc-kit/blob/main/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`](https://github.com/tractorjuice/arc-kit/blob/main/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`](https://github.com/tractorjuice/arc-kit/blob/main/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`](https://github.com/tractorjuice/arc-kit/blob/main/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:

```bash

# 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`](https://github.com/tractorjuice/arc-kit/blob/main/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`](https://github.com/tractorjuice/arc-kit/blob/main/arckit-claude/templates/pages-template.html) through the `sync-guides` hook
- **Customize** the frontend by overriding templates in [`.arckit/templates/pages-template.html`](https://github.com/tractorjuice/arc-kit/blob/main/.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`](https://github.com/tractorjuice/arc-kit/blob/main/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`](https://github.com/tractorjuice/arc-kit/blob/main/index.html), [`manifest.json`](https://github.com/tractorjuice/arc-kit/blob/main/manifest.json), and [`llms.txt`](https://github.com/tractorjuice/arc-kit/blob/main/llms.txt). The site uses client-side JavaScript to load data from [`manifest.json`](https://github.com/tractorjuice/arc-kit/blob/main/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`](https://github.com/tractorjuice/arc-kit/blob/main/arckit-claude/templates/pages-template.html) to [`.arckit/templates/pages-template.html`](https://github.com/tractorjuice/arc-kit/blob/main/.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`](https://github.com/tractorjuice/arc-kit/blob/main/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.