How c2pa-org/c2pa-docs-ui works
Project type and purpose
• This is a front‐end UI project: a “theme” and interaction layer for an Antora/AsciiDoctor‐based documentation site.
• The project bundles Handlebars templates (layouts, partials, helpers), CSS, JavaScript, fonts, and images into a zip that Antora consumes as its UI.
• It provides both local preview capabilities (via a Gulp‐powered dev server) and a CI/CD pipeline for automated releases to GitHub.
File structure
• Top‐level:
• Configuration files (.eslintrc, .stylelintrc, .gitignore, netlify.toml, package.json, gulpfile.js)
• build/ (output artifacts: ui‐bundle.zip)
• gulp.d/ (modular Gulp tasks: build, preview, bundle, lint, release)
• preview-src/ (sample AsciiDoc pages for local preview)
• src/
– css/ (site and component styles, vendor files, typeface definitions)
– js/ (site interactivity modules, vendor libs)
– layouts/ (Handlebars page layouts)
– partials/ (HTML fragments injected into layouts)
– helpers/ (JavaScript helpers for templates)
– img/, font/
• CI:
• .github/workflows/release.yml triggers gulp release on pushes to master.
• package.json scripts (npm start, etc.)
Key insights from README
• Local development: npm install → gulp preview / npm start (watch + live‐reload).
• Bundling: gulp bundle (or bundle:pack) produces build/ui‐bundle.zip.
• Releases: gulp release is CI‐driven, tags the repo, publishes a GitHub Release with the bundle asset.
• Antora integration: users reference the zip in their playbook to apply the UI.
Main components and their interactions
a. Source Repository (GitHub)
• Contains all source files, Gulp tasks, configs.
b. Developer Local Environment
• Node.js + npm dependencies → Gulp CLI → preview server → browser live‐reload.
• Build tasks: compile CSS/JS, copy assets, assemble templates.
c. Build & Packaging Layer (Gulp)
• Tasks: build, lint, preview:build, bundle, pack, release.
• Outputs: site.css, site.js, source maps, ui‐bundle.zip.
d. CI/CD Pipeline (GitHub Actions)
• On push to master: runs gulp release, creates Git tag, GitHub Release, attaches bundle.
e. Artifact Store (GitHub Releases)
• UI bundle ZIP is stored as a release asset.
f. Consumer (Antora)
• Antora playbook references the bundle URL to render the docs site.
g. (Optional) Deployment/Preview Host (Netlify)
• netlify.toml suggests readiness for hosting preview builds.
Architectural patterns and design principles
• Modular Gulp tasks (in gulp.d/) for separation of concerns: build vs. lint vs. release vs. preview.
• Clear separation of source (src/, preview-src/) and build output (build/).
• Template‐driven UI: Handlebars with JavaScript helpers for dynamic content.
• Asset bundling and minification for lean production bundles.
• CI as code: release process automated via GitHub Actions + Gulp.
Detailed layering (top‐down)
1. Developer Workstation
• Clone repo (Git)
• npm install → node_modules
• Run gulp preview → preview server
2. Build Layer (Gulp)
• Tasks read src/ and preview‐src/
• Lint CSS/JS → compile & bundle → build/ui‐bundle.zip
3. CI/CD Layer
• GitHub Actions triggers gulp release
• Creates Git tag & Release → attaches UI bundle
4. Consumption Layer
• Antora playbook references release asset URL
• Docs site generation & deployment (Netlify/Antora host)