How security-alliance/frameworks works
Main Components
a. Content Layer
• Source Markdown files under src/ (chapter content, SUMMARY.md, README.md)
• Configuration files (book.toml, prebuild.sh, serve.sh)
b. Build Engine
• mdBook core (installed via Cargo: mdbook, mdbook-admonish, mdbook-catppuccin)
• Custom plugin: plugin/mdbook-metadata (Rust crate wrapping mdbook-metadata commands)
• Theme assets under theme/ (CSS, JS, Handlebars templates)
c. CI/CD & Validation
• GitHub Actions workflows (.github/workflows/md-lint.yaml, spell-check.yml)
• Pre-build script (prebuild.sh) ensures environment consistency
d. Deployment
• Vercel platform for hosting (triggered by git pushes / Vercel build script vercel_build.sh)
• Production domain planned (frameworks.securityalliance.org)
e. Collaboration/GitHub
• GitHub repo as single source of truth
• Fork & PR workflow (branching model: develop → main)
• Issue templates & pull‐request templates for contribution guidance
Relationships & Data Flow
a. Authoring: Contributors commit Markdown + config files to GitHub.
b. CI Validation: GitHub Actions run linters/spell-checkers on new commits/PRs.
c. Build Pipeline:
• prebuild.sh sets up environment
• mdBook core invokes plugins (mdbook-admonish, mdbook-catppuccin, mdbook-metadata)
• Theme templates & assets are applied to generated HTML.
• Output is a static site in book/ directory
d. Deployment: The static output is pushed to Vercel (via vercel_build.sh or Vercel integration), which serves it under the live URLs.
e. Local Preview: Developers run ./serve.sh (which wraps mdBook serve plus theme/plugin loading) to preview on localhost.
Architectural Patterns & Principles
• Modular pipeline: core engine + plugins + themes
• Content‐as‐data: markdown sources drive site generation
• GitOps: all changes flow through PRs, CI, and automated deploy
• Separation of concerns:
• Content (src/)
• Presentation (theme/)
• Build logic (mdBook + plugins)
• Infrastructure (Vercel, CI workflows)
Essential Elements
• Components:
• GitHub Repository (with branches)
• CI/CD Workflows (lint, spell-check)
• prebuild.sh & serve.sh scripts
• mdBook Core + Plugins + Themes
• Static Site Output (book/ folder)
• Vercel Deployment & Live URLs
• Clear layering: Source → Build → Validation → Deployment