How 18f/development-guide works
Main Components
• Content & Data Sources:
• _pages: Markdown files for individual content pages (e.g., about.md, apis.md, etc.).
• _data: YAML files for site constants and configuration (e.g., favicons, navigation, theme, etc.).
• Templating & Layout:
• _includes: HTML partials and components (for headers, footers, tag styles, etc.) that Jekyll uses to generate the final pages.
• _config.yml: Global configuration settings for Jekyll.
• Styling & Assets:
• _sass: SASS/SCSS files for styling.
• assets: JavaScript, CSS, and image assets.
• Build & Dependency Management:
• Dockerfile and docker-compose.yml: Container configurations for local development and build processes.
• Gemfile and Ruby-related version files (.ruby-version, .bundler-version): Manage Ruby dependencies.
• Package.json & package-lock.json: Manage JavaScript dependencies.
• Continuous Integration & Deployment:
• .circleci and .github directories: Configuration files for CircleCI and GitHub Actions workflows.
• Rakefile: Contains build and test tasks (for link checking, etc.) used in the CI pipeline.
• Documentation & Contribution:
• README.md, CONTRIBUTING.md, and doc/ directory: Guidelines on contributing and reference material related to best practices.
Relationships and Interactions
• Local Content Processing Flow:
• Markdown files in _pages are processed by Jekyll.
• The templates in _includes combine with the data in _data and settings from _config.yml to generate HTML pages.
• SASS files in _sass compile into CSS, which together with JS from assets create a cohesive frontend.
• Build and Deployment Workflow:
• Docker containers (as specified by Dockerfile and docker-compose.yml) provide an isolated environment for running Jekyll.
• CI/CD pipelines (CircleCI and GitHub Actions) are configured to build, test, and deploy the generated static site.
• Automated Rake tasks are used within the Docker container to test internal links and validate site integrity.
• Version Control and Collaboration:
• GitHub structure (with .github workflows and CONTRIBUTING.md) supports open collaboration, code reviews, and automated checks.
Architectural Patterns and Design Principles
• Static Site Generation: The project follows a standard static site architecture using Jekyll with clear separation between content (markdown), layout (templates), and styling.
• Containerized Development: The use of Docker ensures consistent development and build environments.
• CI/CD Integration: Automated workflows ensure site quality through link checking and testing.
• Modular Design: Splitting templates, Sass, and content into distinct directories makes the system extensible and maintainable.
Final Checklist
• Clear, legible labels for each directory component (Content, Templates, Assets, Build Environment, CI/CD).
• Annotations that include key technologies: Jekyll, Docker, Ruby, Node.js, CircleCI, and GitHub Actions.