How mulesoft/docs-accelerators works
Project Type & Purpose
• This repository is not an application or service but a static documentation site built with Antora, organizing AsciiDoc-based documentation for multiple “accelerator” modules (e.g., consumer-goods, financial-services, healthcare, etc.) and their versioned releases.
• The goal is to maintain modular, versioned docs for each domain area, render them into a unified website, and publish the static site to a hosting platform (e.g., GitHub Pages, S3/CloudFront).
File Structure Analysis
• Top-level directories (accelerators-cim/, consumer-goods/, financial-services/, healthcare/, retail/, etc.) each contain versioned subfolders (1.3/, 2.0/, 3.0/, …), each with:
• an antora.yml descriptor
• a modules/ROOT/pages tree of .adoc files
• optional assets (images, Graffle files)
• The modules/ROOT/pages/accel folder holds global/shared AsciiDoc content.
• Root files (README.adoc, CODE_OF_CONDUCT.adoc, etc.) govern repository-wide policies and may seed the Antora playbook.
Key Insights from README
• Minimal content; focuses on contribution guidelines, licensing, and security.
• No runtime code or server components—Antora is invoked to compile the docs.
Components
a. Git Repository (Source)
• Houses all versioned content modules and documentation policies.
b. Antora Playbook & UI Bundle
• Playbook (typically antora-playbook.yml) references modules via file paths.
• UI Bundle (themes, templates, CSS/JS) provides branding and layout.
c. AsciiDoc Processor & Node.js
• Underlying engine invoked by Antora CLI to convert .adoc → HTML.
d. Build/CI System
• CI pipeline (GitHub Actions / Jenkins / Travis) triggers on push/PR:
• Lints AsciiDoc
• Runs Antora build
• Uploads artifacts
e. Static Site Output
• Directory of generated HTML/CSS/JS/images.
• Packaged and deployed to hosting (S3 bucket / GitHub Pages / CDN).
f. Hosting & CDN
• Serves static files with low latency.
• Optional search index (ElasticSearch or Algolia) for full-text search.
g. End Users / Contributors
• Browser clients consume the static site.
• Contributors submit PRs back to Git repo.
Relationships & Data Flow
• Developers/Contributors → commit .adoc changes → Git
• CI System fetches repo → runs Antora CLI + AsciiDoc Processor using Playbook + UI Bundle → produces Static Site
• CI deploys static output to Hosting/CDN → End User Browsers fetch pages
• (Optional) Search Service consumes generated search index during build, serves search queries client-side
Architectural Patterns & Principles
• Modular Composition: Each domain/version is an independent module. Antora aggregates them into one site.
• Content Versioning: Parallel version folders allow historical docs.
• Separation of Concerns:
• Content (AsciiDoc) vs. Presentation (UI bundle) vs. Build Logic (playbook, CI).
• Immutable Deployment: Static artifacts ensure predictable, cacheable delivery.
Relevant Technologies & Frameworks
• Antora (documentation site generator)
• AsciiDoc (markup)
• Node.js (runtime for Antora CLI)
• Git/GitHub (source control and PRs)
• CI/CD (GitHub Actions / Jenkins / Travis)
• CDN/Hosting (S3, CloudFront, GitHub Pages)
• Search (optional Algolia or Lunr.js)