Documentation Site

The /docs directory contains the source files for the Jekyll-powered static documentation website deployed to GitHub Pages.

Documentation Website

Overview

This documentation website uses:

Jekyll 4.3.4 - Static site generator
just-the-docs theme - Clean documentation theme
Ruby 3.2.3 - Runtime environment (in WSL for local builds)
Custom plugins - To copy README files and static assets
Python scripts - To generate documentation from Git commits and API client. See /scripts/README.md
GitHub Actions - For automated deployment. See /.github/workflows/README.md

The site is deployed to: https://metanull.github.io/inventory-app

Directory Structure

Manually Maintained Content

These files are written and maintained by developers:

Directory/File	Purpose
`index.md`	Site homepage
`guidelines/`	Backend development guidelines and conventions
`development/`	Development documentation (contributing, testing)
`deployment/`	Deployment guides and server configuration
`frontend-blade/`	Blade frontend documentation
`frontend-vue-sample/`	Sample Vue.js SPA documentation
`api/`	API overview and endpoint documentation
`models/`	Index pages for model documentation

Auto-Generated Content

These files are created by scripts or plugins and should not be manually edited:

Directory/File	Generated By	Description
`_docs/`	`generate-commit-docs.py`	Git commit history converted to markdown. See /scripts/README.md
`api-client/`	`generate-client-docs.py`	TypeScript API client documentation. See /scripts/README.md
`_model/`	`generate-model-documentation.ps1`	Laravel model documentation (schemas, relationships). See /scripts/README.md
`development/scripts.md`	Plugin: `copy_readme_files.rb`	Copy of `/scripts/README.md`
`development/workflows.md`	Plugin: `copy_readme_files.rb`	Copy of `/.github/workflows/README.md`
`_openapi/api.json`	Laravel Scramble	OpenAPI specification for the API
`_openapi/swagger-ui.html`	Manual	Swagger UI for browsing the API
`_site/`	Jekyll build process	Generated static HTML site

Jekyll Configuration

File/Directory	Purpose
`_config.yml`	Main Jekyll configuration (theme, plugins, collections)
`_plugins/`	Custom Ruby plugins for site generation
`_layouts/`	Custom page layouts (extends just-the-docs theme)
`assets/`	Images, CSS, and other static assets
`Gemfile`	Ruby dependencies

Content Generation

Plugin: Copy README Files

File: _plugins/copy_readme_files.rb

Copies README files from the repository root into the documentation during Jekyll build.

Behavior:

Runs on Jekyll after_init hook (before site generation)
Copies /scripts/README.md → /docs/development/scripts.md
Copies /.github/workflows/README.md → /docs/development/workflows.md
Copies /docs/README.md → /docs/development/documentation-site.md
Adds Jekyll front matter with title, parent, and permalink
Removes original # Title heading (replaced by front matter title)

Output:

/development/scripts/ - Scripts documentation
/development/workflows/ - GitHub Workflows documentation
/development/documentation-site/ - Documentation website architecture and build process

Plugin: Copy Static Files

File: _plugins/copy_static_files.rb

Copies static files to the site root after Jekyll builds the site.

Behavior:

Runs on Jekyll post_write hook (after site generation)
Copies _openapi/api.json → _site/api.json
Copies _openapi/swagger-ui.html → _site/swagger-ui.html

Output:

/api.json - OpenAPI specification at site root
/swagger-ui.html - Swagger UI at site root

Links:

Script: Generate Commit Documentation

Script: scripts/generate-commit-docs.py

Converts Git commit history into Jekyll-compatible markdown pages.

Invoker:

CI/CD workflow on push to main. See /.github/workflows/README.md
Can be run locally: python scripts/generate-commit-docs.py

Input: Git repository history

Output: /docs/_docs/**/*.md - One markdown file per commit with front matter

Integration: Files are automatically included via Jekyll collections (_docs)

See: /scripts/README.md for details

Script: Generate API Client Documentation

Script: scripts/generate-client-docs.py

Transforms TypeScript API client markdown into Jekyll-compatible pages.

Invoker:

CI/CD workflow on push to main. See /.github/workflows/README.md
Can be run locally: python scripts/generate-client-docs.py

Input: /api-client/docs/*.md - Auto-generated TypeScript docs

Output: /docs/api-client/*.md - Jekyll-ready markdown with fixed links

Integration: Files are automatically included during Jekyll build

See: /scripts/README.md for details

Building the Site

Local Development

Build the site:

# Build static site to docs/_site/
. ./scripts/jekyll-build.ps1

# Build with custom base URL
. ./scripts/jekyll-build.ps1 -BaseUrl "/my-app"

Serve locally:

# Start development server at http://localhost:4000
. ./scripts/jekyll-serve.ps1

# With LiveReload
. ./scripts/jekyll-serve.ps1 -LiveReload

# Custom port
. ./scripts/jekyll-serve.ps1 -Port 8080

Requirements:

WSL (Windows Subsystem for Linux)
Ruby 3.2.3+ installed in WSL
Jekyll and Bundler gems: bundle install in /docs

See: /scripts/README.md for script details

Production Deployment

The site is automatically deployed to GitHub Pages via CI/CD.

Workflow: .github/workflows/continuous-deployment_github-pages.yml

Process:

Checkout repository with full Git history
Set up Python and Ruby environments
Run generate-commit-docs.py to create commit documentation
Run generate-client-docs.py to create API client documentation
Build Jekyll site with bundle exec jekyll build
Upload artifact to GitHub Pages
Deploy to production

Trigger: Push to main branch or manual workflow dispatch

See: /.github/workflows/README.md for workflow details

Theme and Configuration

Theme: just-the-docs

Clean, responsive documentation theme
Built-in search functionality
GitHub integration for “Edit this page” links
Customizable navigation and color schemes

Key Configuration (_config.yml):

Setting	Value	Purpose
`remote_theme`	`just-the-docs/just-the-docs`	Use just-the-docs theme from GitHub
`baseurl`	`/inventory-app`	GitHub Pages subdirectory
`url`	`https://metanull.github.io`	GitHub Pages domain
`search_enabled`	`true`	Enable site-wide search
`gh_edit_link`	`true`	Show “Edit on GitHub” links
`collections`	`_posts`, `_docs`	Enable blog posts and commit docs

Plugins:

jekyll-sitemap - Generates sitemap.xml
jekyll-feed - Generates RSS feed
jekyll-seo-tag - Adds SEO meta tags

Navigation:

Pages with nav_order appear in sidebar
Pages with parent create hierarchical navigation
Pages with has_children create expandable sections

Front Matter Example:

---
layout: default
title: Page Title
parent: Parent Page
nav_order: 3
permalink: /custom-url/
---

Contributing

When adding or updating documentation:

Manual content: Edit markdown files in appropriate directories
Auto-generated content: Run the appropriate script or let CI/CD handle it
Test locally: Use jekyll-serve.ps1 to preview changes
Build verification: Run jekyll-build.ps1 to check for errors
Commit and push: Changes are automatically deployed on push to main

Important:

Do not manually edit files in _docs/, _model/, or api-client/ - they are auto-generated
Always run scripts from the project root directory
Validate workflow changes with node scripts/validate-workflows.cjs. See /scripts/README.md

Cross-references:

Scripts documentation: /scripts/README.md
Workflows documentation: /.github/workflows/README.md

Table of contents