How owasp/www-project-web-security-testing-guide works
Project Type & Purpose
• This is a Jekyll‐based static site generator for the OWASP Web Security Testing Guide (WSTG) landing page on owasp.org.
• It pulls in Markdown content (versioned under folders like latest/, stable/, v41/, v42/), data files (_data/*.yaml), layouts/includes (_includes/), config (_config.yml), and assets (assets/), then produces HTML/CSS/JS for deployment.
File Structure & Architectural Patterns
• Content Directories: latest/, stable/, v41/, v42/ each contain Markdown chapters and front matter (info.md, index.md).
• Templates & Includes: _includes/ (header, nav, breadcrumbs), default layouts in Jekyll’s _layouts/ (implied).
• Data Layer: _data/ YAML/JSON files feed the templates with dynamic sidebars, version lists, attributions.
• Assets Pipeline: assets/ holds images, archived downloads, CSS/JS handled by Jekyll or plugins.
• Configuration: Gemfile + bundle install, _config.yml define plugins, base URL, build options.
• CI/CD: .github/workflows/pr_comment.yml integrates with GitHub Actions for PR checks; additional workflows will handle build & deployment.
Key Components
a. Developer Environment
• Local machine with Ruby, Bundler, Jekyll CLI.
• Source code (Markdown, templates, config).
b. Version Control & CI
• GitHub repo triggers Actions on push/PR.
• CI job: bundle install → jekyll build → artifact verification.
c. Build Engine
• Jekyll (Ruby) + any plugins (Liquid templating, data ingestion).
• Input: content + data + templates.
• Output: static site under _site/.
d. Deployment/Hosting
• GitHub Pages or OWASP infrastructure (could be a static‐hosting bucket + CDN).
• Delivery via CDN (e.g., CloudFront or Netlify).
e. End Users
• Browsers requesting HTML, CSS, JS, images.
Relationships & Data Flow
• Developer makes changes → git push → GitHub Actions → Jekyll build → static artifacts → deploy to hosting → CDN cache → end user.
• Data/_data YAML → fed into templates → generates navigation menus, version selectors.
• Assets copied directly into output and served.
Important Architectural Principles
• Separation of Concerns: content (Markdown) vs presentation (layouts/includes) vs data (YAML).
• Static Generation: no backend runtime; build‐time assembly.
• CI/CD Pipeline: ensures validity of link references, layout consistency, correct asset paths.
• Extensibility Points: Jekyll plugins, Liquid includes for new sections or versions.
Must‐Have Elements
• Annotations for technologies: “Ruby + Jekyll”, “Liquid templates”, “GitHub Actions”, “GitHub Pages/CDN”.