How colinwilson/lotusdocs works
Project Type and Purpose
• Project type: A Hugo-based static documentation theme
• Purpose: Provide a customizable, SEO-friendly, multi-lingual docs site theme that users can integrate into their Hugo projects
File Structure
• Top-level directories:
– archetypes/ (default front-matter templates)
– assets/ (SCSS, JS, images for theme styling and docs site)
– data/ (YAML data files used by templates)
– exampleSite/ (an example Hugo site using the theme)
– i18n/ (translation files)
– layouts/ (theme’s HTML templates and shortcodes)
• Configuration files: config.toml, netlify.toml, theme.toml
• CI workflow: .github/workflows/codeql-analysis.yaml
Extract Architectural Insights from README
• The theme is a Hugo Module, importing:
– “colinwilson/lotusdocs” (this repo)
– “gohugoio/hugo-mod-bootstrap-scss” (Bootstrap SCSS module)
Main Components to Model
A. Content Layer
– Markdown files in content/ (inside exampleSite)
– Data files (landing.yaml)
– i18n translation bundles
– Archetypes (default front-matter templates)
B. Theme Code (Lotus Docs module)
– layouts/ (page templates, partials, shortcodes)
– assets/ (SCSS → CSS pipeline, JS bundles, images)
– config.toml & theme.toml (default theme parameters)
C. External Modules & Libraries
– Hugo Bootstrap SCSS Module
D. Build Engine
– Hugo (Extended)
– Hugo Modules system (module imports, replacements)
E. CI/CD Pipeline
– GitHub Actions for code scanning (CodeQL)
– netlify.toml (deploy configuration)
– Potential deployment targets: GitHub Pages, Netlify, Vercel, Cloudflare Pages
F. Runtime / Hosting Layer
– Static assets (HTML, CSS, JS, images, fonts) served from CDN / SSG host
– Client‐side: Syntax highlighting, dark mode toggle, search index
Relationships & Data Flows
• Author writes Markdown + updates data/i18n →
Hugo (build) loads theme code + external modules →
Processes SCSS, JS, templates →
Outputs static site artifacts →
CI/CD pushes artifacts to host →
End-users’ browsers fetch static assets and run client-side JS plugins
Architectural Patterns & Design Principles
• Static-site generator pattern
• Module composition (Hugo Modules)
• Separation of concerns: content vs. presentation vs. build logic
• Plugin-based extensibility (shortcodes, SCSS partials, JS bundles)
Capturing Essential Details
• Don’t omit:
– Archetypes (front-matter templates)
– data/ and i18n/ as inputs to layouts
– exampleSite/ as a live demo consumer
– The role of SCSS and JS under assets/ and assets/docs/
• That the output is purely static; client runs JS plugins for search, syntax highlighting, dark mode, etc.