How haufe-lexware/api-style-guide works
Project type and purpose
• This is an open-source documentation repository—a style guide for RESTful API design.
• Its “architecture” isn’t a service mesh or microservices mesh, but a content-pipeline: markdown source → static site generator → hosted static website.
Main components
a. Content Layer (Source)
• All .md files under top-level folders (e.g., introduction/, api-design-principles/, etc.) plus README.md, SUMMARY.md, _config.yml.
• Git repo holds version history, branching, PRs for updates.
b. Build Layer (Static Site Generator)
• Likely Jekyll (due to _config.yml) or GitBook (due to SUMMARY.md).
• Parses Markdown + YAML config → produces HTML/CSS/JS.
c. CI/CD Layer
• (If present) GitHub Actions / Travis CI / similar to install dependencies, run jekyll build or gitbook build.
• Runs linting/spellcheck, deploys on push to gh-pages or designated branch.
d. Hosting & Delivery Layer
• GitHub Pages or a CDN (e.g., Netlify) serves the compiled static site.
• TLS, caching headers, custom domain.
e. Consumers
• API designers, developers who browse via browser.
• Can file issues or PRs—integrated via GitHub UI.
Relationships & Data Flow
1. Developer writes/edits Markdown in repo →
2. Commit & PR opened → CI job triggers (lint, spellcheck). →
3. On merge, SSG builds static assets →
4. CI deploys to hosting environment →
5. User’s browser requests HTML/CSS/JS →
6. CDN/GitHub Pages serves content.
Architectural patterns & design principles
• Content-Pipeline pattern: strict separation of content (Markdown) and presentation (templates & CSS).
• GitOps/Infrastructure-as-Code: define build & deploy via YAML config in repo.
• Modular organization: each chapter is a folder with its own .md, enabling easy extension.
Key technologies
• Markdown (content format)
• Jekyll or GitBook (static site generator)
• YAML config (_config.yml, SUMMARY.md)
• GitHub (version control, PR workflow, Pages hosting)
• CI tool (e.g., GitHub Actions, Travis CI)
• CDN (optional)
e. Underline extension points on “Content Repo”: new chapters, pull requests.