How deepfence/documentationwebsite works
Main Components
• Documentation Aggregator: The central Docusaurus site (found under the “docs” directory) that builds the aggregated website.
• Product Documentation Submodules: Located in the “product-docs” folder, these are the individual project documentation sources brought in via git submodules.
• Skeleton Templates: In the “skel” directory, which provides a template for adding documentation to new products.
• Build and Import Process: The Makefile and associated scripts (e.g. bootstrap.sh, docker-entrypoint.sh, import.pl) that handle updating submodules, copying over content, and modifying metadata for SEO and navigation.
• Docker and Deployment: Docker-related files (Dockerfile, .dockerignore, nginx config snippets in the README) which illustrate how the final static site is built, containerized, and deployed.
• Local Development and Build Tools: Tools such as yarn and npm configurations (package.json, yarn.lock) and Docusaurus configuration files (docusaurus.config.js, sidebars.js) that determine the presentation layer and navigation.
Relationships and Interactions
• The build process (Makefile) orchestrates the collection of documentation from the “product-docs” submodules, applying transformations (via import.pl) and integrating sidebar navigation information.
• The Docusaurus configuration (in “docs/docusaurus.config.js” and “docs/sidebars.js”) defines how the aggregated content is organized into a cohesive site.
• Docker is used to build and run the production container, with deployment instructions provided (NGINX configuration and TLS setup in the README).
• The “skel” directory serves as a guideline for new projects to follow so that their documentation is compatible with the aggregated site.
Important Architectural Patterns or Design Principles
• Modularity: Each product documentation is maintained as an independent git submodule. This separation facilitates independent development while being integrated into the centralized documentation site.
• Automated Build and Import Pipeline: The use of Makefile commands to update submodules and import documentation ensures that the entire site remains in sync and builds consistently.
• Static Site Generation: Leveraging Docusaurus 2 to produce a static site improves performance and allows for easy deployment via containerization.
Relevant Technologies, Frameworks, and Tools
• Docusaurus 2: The main framework for the documentation website.
• Git and Git Submodules: Used to include documentation from separate product repositories.
• Docker: Containerization for building and deploying the production-ready website.
• NGINX: Suggested for reverse-proxying and hosting the static site, with configurations provided in the README.
• Yarn (and Node.js): For dependency management and local development.
• Makefile and Shell Scripts: For automating the build and import processes.
Elements
• From individual product documentation (in submodules) to the Import Process.
• From the Import Process to the Docusaurus build which renders the static site.
• From the build output to Docker and then to NGINX for deployment.
• Source code/configuration components (directories like docs, product-docs, skel).
• Build and integration tools (Makefile, scripts).
• Deployment and runtime environment (Docker, NGINX, hosting domains).