How openstreetmap/stateofthemap-2025 works
• Content Repository: Represent the Git-controlled repository which contains all source files. Break this down into components:
• Markdown Content (e.g., in “calls” and “venue” directories; index.html, imprint)
• Templates: “_layouts” folder (layouts for pages, sessions, redirect, etc.)
• Includes: “_includes” folder (partial HTML snippets like header, footer, nav, CSS and JS includes)
• Static Assets: “css”, “js”, “img”, “fonts" directories.
• Additional Assets: Supporting files such as “LICENSE”, “.editorconfig”, and configuration files (e.g., _config.yml for Jekyll configuration)
• Jekyll Build Process: Show how Jekyll reads the configuration (_config.yml), uses the layouts and includes to merge with markdown content, and generates the final static HTML files.
• Directly indicate the use of the Jekyll static site generator and how it processes markdown files and transforms them into HTML using Liquid templates.
• Development and Deployment Environment:
• Local Development: Show the developer’s local environment running Jekyll via “jekyll serve” on port 4000.
• Containerized Environment: Represent Docker (Dockerfile, docker-compose.yml, and docker-compose.override.yml) as an alternative build/run method.
• CI/CD Pipeline: Optionally include the GitHub Actions workflows (in .github/workflows) that might auto-test or deploy the site upon incoming commits or pull requests.
• External Integration:
• Although the site is static, note that the program schedule (sessions) is managed externally via the Pretalx submission system. Add an external component for Pretalx (an external service) that feeds data (indirectly through API or automated updates) into the website.
Relationships and Data Flow
• Content and templates from the repository feed into the Jekyll build process.
• The Jekyll engine processes templates, markdown, and assets to output a static site.
• The resulting static site is then served (either via the local “jekyll serve” mechanism or in production via a web server, potentially running inside a Docker container).
• A note on external updates from the Pretalx system: indicate that changes on the submission system may automatically update specific parts of the generated content (e.g., sessions).
• Optionally, link CI/CD steps (GitHub Workflows) that run test/build procedures before deployment.
Architectural Patterns & Technologies
• Static Site Generation: Emphasize that Jekyll is central as it converts markdown and templates into a static website.
• Separation of Concerns: Organize components into content, presentation (layouts, includes, CSS/JS), and build/deployment pipelines.
• Containerization: Mention Docker components (Dockerfile, docker-compose) that encapsulate the Jekyll environment.
• Version Control & CI/CD: Show how source versioning (Git) and GitHub Actions integrate into the overall workflow.