How alshedivat/al-folio works
Main components
• Source Content & Configuration: This includes the core “content” directories such as _posts, _pages, _data, _bibliography, _includes, _layouts, and _sass. These folders collectively represent the raw inputs that the static site generator (Jekyll) uses to produce the final website.
• Build & Templating Engine (Jekyll Core): The theme relies on Jekyll for processing Liquid templating, applying configuration (_config.yml), and generating static HTML websites. In addition, custom plugins from the _plugins directory provide extended functionality (e.g., custom Liquid tags, citation formatting, GitHub repository stats, etc.).
• Asset Pipeline: The assets directory holds media (images, CSS, JavaScript, audio, video, etc.). This component supplies the style (via SCSS in assets/css and _sass) and interactive features via JavaScript.
• Continuous Integration / Deployment: GitHub workflows (files in .github/workflows) and Dockerfiles ensure that code quality checks (Prettier, lychee for links, Axe for accessibility), linting, and build deployments occur automatically. Docker Compose files and scripts in the bin directory reinforce this automated build/deploy process.
• External Services & Third-Party Integrations: Third-party APIs and services are integrated in several places:
▪ GitHub-readme-stats and trophy renders for repository stats.
▪ Jekyll Scholar for bibliography and publications.
▪ Lighthouse (with test reports in lighthouse_results) for performance monitoring.
▪ Social media metadata generation (Open Graph tags) configured via _config.yml.
• Hosting Platform/Delivery: The final generated website (static HTML, CSS, JS) is generally deployed on GitHub Pages, served via a containerized build when using Docker, or deployed via CI/CD defined in GitHub workflows.
Relationships & interactions
• Content and configuration files are fed into the Jekyll engine that uses the Liquid templating provided in _layouts and _includes.
• The rendering process incorporates asset compilation (SCSS to CSS, JS by bundling if needed) and uses plugins to extend Jekyll’s behavior (e.g., incorporating bibliography content, dynamic CV building).
• The CI/CD pipelines and Docker container definitions wrap the build process and run tests before deployment.
• The generated static site is then served to end users (often via GitHub Pages) with external services (e.g., GitHub APIs for stats or Lighthouse for performance) interfaced as needed.
Architectural patterns & design principles
• Modular Template Structure: The project strictly separates content (_posts, _pages) from presentation (_layouts, _includes, _sass) and configuration (_config.yml, _data). This ensures maintainability and flexibility in customization.
• Plugin and Extension Mechanism: Custom Ruby plugins extend the templating engine to process specialized content (e.g., citations, CV elements), indicating adherence to the extension-based architecture common in static site generators.
• Automated CI/CD Pipeline: GitHub workflows automate quality control, deployment, and even Docker builds. This indicates a design where continuous integration is key to ensuring high quality and a reliable release process.
• Asset Management and Responsive Design: With dedicated asset folders and a range of JavaScript libraries (for functionalities like charts, code highlighting, and accessibility tools), the project emphasizes an interactive and responsive user experience.