How nokia/owasp-cheatsheetseries works
Main Components
• Content Repository – The source material is mainly stored in the “cheatsheets” directory (with published cheat sheets) along with “cheatsheets_draft” and “cheatsheets_excluded” for works in progress or archived content.
• Asset Store – The “assets” folder contains supplementary files like ZIP archives, PDFs, code samples, and additional documentation that support the cheat sheets.
• Build and Automation Scripts – The “scripts” directory includes multiple Python and shell scripts for tasks like generating the cheat sheet table-of-contents, RSS feeds, and site builds. A “book.json” and “mkdocs.yml” file indicate that the system uses static site generation (with MkDocs) to build the offline website.
• CI/CD and Workflow Management – The “.github” folder encapsulates GitHub Actions workflows (build, deploy, link checking, linting, etc.) which automatically manage testing, validation, and deployment of the website.
• Templates and Configuration – The “templates” directory stores standardized markdown templates (for new cheat sheets), while configuration files like “package.json”, “.markdownlint.json”, and “.textlintrc” ensure code quality and consistency.
Relationships and Data Flow
• Content Flow: Markdown files in the “cheatsheets” directories become the primary content. They are processed by custom scripts (in “scripts”) and assembled using configuration in “mkdocs.yml” to generate the static website.
• Build Automation: On each commit or pull request, GitHub Actions (defined in “.github/workflows”) trigger linting, link checks, and build scripts. The outcome of these actions is the generation and deployment of a bundled ZIP archive for offline use and an updated online website.
• Developer Interaction: Contributors add or update cheat sheets (using templates from “templates”) and use scripts to update the indexes, RSS feed, and other dynamic lists, all while following the contributions guidelines detailed in files like CONTRIBUTING.md and CODE_OF_CONDUCT.md.
Architectural Patterns & Design Principles
• Static Site Generation: The project leverages a static site generator (MkDocs) for turning markdown content into a polished website.
• CI/CD Integration: Automated workflows ensure that the content is continuously integrated, checked, and deployed. This separation of content, build automation, and deployment reflects modular design principles.
• Version Control and Contribution Flow: With clearly separated directories for drafts (“cheatsheets_draft”) and published content (“cheatsheets”), there is a natural separation of stages in content readiness, which helps in tracking changes and quality control.