How joelouthan/theologicus works
Main components
• Content Repository: Represented by the “src” directory, it holds all Markdown files for multiple books, sermons, confessions, and biblical texts. Also include ancillary content such as notes and bibliographies.
• Build & Static Site Generator: The project relies on mdBook (and its associated “mdbook-toc” tool in the “bin” folder) to process the Markdown content into a navigable website.
• Theming & Presentation Layer: The “theme” directory holds Handlebars templates (e.g., head.hbs, index.hbs), CSS files (including Chrome, print, and general CSS), fonts, and any JavaScript needed for interactivity.
• Configuration & Metadata: Files like book.toml (for mdBook configuration) and various .json/.toml files that inform the build process.
• Deployment Pipeline: The “netlify” folder (with edge functions) indicates how the site is deployed and served by Netlify. Also include version control (.gitignore, .gitmodules) among the infrastructure components.
• Utilities & Editor Support: Additional folders (.vscode, code-workspace files) support developer experience.
Relationships and interactions
• The Content Repository (Markdown files in “src”) is fed into the Static Site Generator (mdBook) that reads the configuration from book.toml.
• The Static Site Generator uses the theming assets (from the “theme” folder) to apply a consistent look and feel to the generated pages.
• The build process may also invoke utility tools (like the custom “mdbook-toc” from the “bin” folder) to generate or update tables of contents.
• Once the site is built, it is deployed via the Netlify pipeline (with custom edge functions for dynamic behaviors) that serves the final HTML/CSS/JS to end users.
• Version control and workspace files (.git, .vscode, .code-workspace files) are used during development to manage and maintain the content and build scripts.
Important architectural patterns and design principles
• Separation of Concerns: Notice how the project splits content (Markdown files) from presentation (theme files) and build configuration (book.toml and supporting scripts).
• Static Site Generation: The use of a tool like mdBook underscores a pattern where content is pre-rendered into static pages that can be hosted on a CDN (via Netlify).
• Modularity and Extensibility: With multiple submodules (evident from the .gitmodules file and versioned releases) and external deploy pipelines, the design anticipates changes and integrations (like a Swift port or submodules for 1689).
• Configuration-driven builds: The presence of several configuration files (e.g., for the Markdown linter and workspace settings) indicates an emphasis on automation and standardization in the build and deployment process.
Relevant technologies, frameworks, and libraries
• mdBook and mdbook-toc for static site generation.
• Markdown as the primary content language.
• Handlebars (indicated by .hbs files in the theme) for templating.
• CSS and JavaScript (including custom “book.js”) for styling and interactivity.
• Netlify for deployment and custom edge functions (JavaScript files such as “blockUserAgent.js” and “hello.js”).
• Auxiliary tools (VSCode for development, Git for version control, and possibly Rust given mdBook’s Rust ecosystem).