How calcobalt/pagefull works
Main Components
• Source Content & Configuration:
• Markdown pages and posts: Directory _posts (with Markdown files), _tabs, and index.html.
• Configuration files: _config.yml, Gemfile, and various dotfiles.
• Data files: Directory _data (with authors, locales, etc.), which feed structured information (e.g., authors, media, origins).
• Presentation & Styling:
• Layouts: Directory _layouts provides various page templates (home.html, post.html, tag layouts, etc.).
• Includes/Partials: Directory _includes contains reusable HTML snippets (analytics, embed, navigation, sidebar, etc.).
• Styles: The _sass directory holds the SCSS files, abstract files, component and layout styles, themes (dark/light), vendor styles like Bootstrap; assets/css and assets/img also support the visual aspect.
• Interactive & Client-Side Enhancements:
• JavaScript: The _javascript directory contains JS functionality split into modules for components (back-to-top, search, image handling, etc.) and PWA support (sw.js, app.js) for offline capability.
• Asset bundling: Files such as package.json, rollup.config.js, and purgecss.js indicate a build process for CSS/JS optimization.
• Build & Deployment:
• Jekyll Build Process: The Jekyll engine uses the configuration, layouts, includes, and markdown posts to generate the static site.
• Workflows/Deployment: GitHub workflows (in .github/workflows) outline CI/CD and GitHub Pages deployment.
• Dev Containers: The .devcontainer folder and related configuration support containerized development environments.
Relationships and Interactions
• Input and Configuration:
• The Jekyll build engine reads _config.yml, metadata from _data files, and each Markdown post’s front matter.
• Gemfile (and gemspec) define Ruby dependencies required for building the theme.
• Thematic Rendering:
• Content is processed by layouts (_layouts) using “includes” components to assemble the final HTML.
• SCSS files in _sass are compiled (likely via a build tool like Rollup and configured in package.json) to generate styling, which is then rendered by the layouts.
• Enhancements and Interactivity:
• JavaScript modules enhance behavior on the client side (e.g., search interaction, PWA service worker registration, comment system integrations).
• External services/analytics integrations are managed via specific partials in _includes (for Google Analytics, Matomo, etc.)—these are injected into site pages.
• Build and Deployment Pipeline:
• Local development is aided by dev container configurations; CI workflows (GitHub Actions) monitor commits and deploy via GitHub Pages.
• Rollup and other build scripts (tools/run.sh, tools/test.sh) orchestrate asset bundling and website optimizations.
Architectural Patterns and Design Principles
• Separation of Concerns: There is a clear separation between content (posts, data), presentation (layouts, includes, SCSS), and interactive behavior (JavaScript modules).
• Modularity and Extensibility: The theme is designed to be configurable (with data files, localized content, theming via separate SCSS files) and supports plugin-like integrations (e.g., different comment systems and analytics engines).
• Static Generation Pipeline: The system leverages Jekyll’s static site generation pipeline and incorporates modern build tools (Rollup, PurgeCSS for optimization, and PWA support) to improve performance and maintainability.
Relevant Technologies and Frameworks
• Ruby and Jekyll: The backbone for static site generation.
• SCSS/CSS: For styling with modular organization under _sass.
• JavaScript: Custom modules, PWA support (service workers), and enhancement scripts under _javascript.
• GitHub Actions and Dev Containers: For CI/CD and reproducible development environments.
• External libraries integrated via partials (e.g., analytics, comment systems, and embed providers).