How accordproject/techdocs works
Main Components
• Documentation Content – This includes the “docs” directory (with various markdown files and versioned documents) where the bulk of the content (tutorials, specifications, guides) resides.
• Website Frontend – Located under the “website” directory, it holds the Docusaurus configuration (site config, pages, sidebars, scripts, and static assets) that turns the documentation content into a navigable website.
• Assets and Supporting Files – The “assets” folder contains images, PDFs, and other media used in branding and documentation.
• CI/CD and Build Infrastructure – The “.github/workflows” directory and various build scripts (e.g., in “scripts” and parts of “docs/assets/architecture”) indicate that continuous integration (build and publish) is used to generate and deploy the site.
• Versioning Infrastructure – The “website/versioned_docs”, “website/versioned_sidebars”, and “website/versions.json” directories manage multiple versions of documentation, which is critical for serving legacy and current information.
Relationships and Interactions
• The Documentation Content (docs/...) feeds into the Website Frontend during the build process. Docusaurus takes the content and renders static HTML pages.
• The build process (triggered via GitHub workflows) pulls the latest changes from the repository, compiles the website (using configuration files from the “website” directory and build scripts), and then deploys the generated static site.
• The assets are referenced both by the docs and the website’s static directories.
• Version control and CI/CD ensure that updates (both to technical content and website configuration) are automatically reflected on the live site (https://docs.accordproject.org) once the build and deployment pipeline passes.
Architectural Patterns and Technologies
• Static Site Generation – The use of Docusaurus means that the system is built on a static site generator architecture. The content is written in markdown and transformed into a static HTML site.
• Versioning – A key design element is the management of multiple versions of documentation, indicated by the “versioned_docs” and “versioned_sidebars” directories.
• Separation of Concerns – Clearly divided between documentation (content) and website code (presentation and rendering), along with build and deployment automation (via CI/CD workflows).
• Open Source and Collaboration – Configuration files like CONTRIBUTING.md, DEVELOPERS.md, and GitHub templates highlight community collaboration processes.