How maximevaillancourt/digital-garden-jekyll-template works
Project type and purpose
• This is a Jekyll-based static site generator template designed to power a “digital garden” (interlinked Markdown notes, Roam-style double brackets, backlinks graph).
• Its main goal is to transform a folder of Markdown notes and pages into a static website with custom plugins (bidirectional link generator, embed-tweet, etc.), Sass styling, and deploy it (Netlify or GitHub Pages via GitHub Actions).
File structure
• Top-level config & CI/CD:
• _config.yml – core Jekyll settings
• Gemfile / Gemfile.lock – Ruby + Jekyll + plugin dependencies
• netlify.toml – Netlify build & deploy instructions
• .github/workflows/jekyll.yml – GitHub Actions CI for building & deploying to GitHub Pages
• Content directories:
• _notes/ – Markdown files for each note (includes nested subfolders)
• _pages/ – site-level pages (about, index)
• Theming & templating:
• _layouts/ – HTML templates (default, page, note)
• _includes/ – partials (nav, footer, graph script, link-preview)
• _sass/ & styles.scss – styling, partial Sass files
• assets/ – media (e.g., MP3)
• Custom plugins:
• _plugins/*.rb – Ruby scripts that run during Jekyll build (generate bidirectional_links, graph JSON, last_modified, external link handling, etc.)
Additional insights from README
• Highlights interactive notes graph powered by a JSON file generated at build time.
a. Main components
1) Content store (Markdown in _notes & _pages)
2) Jekyll build engine (reads config, content, layouts, includes, Sass, plugins)
3) Custom plugin layer (Ruby classes generating notes_graph.json, backlinks, etc.)
4) Theming layer (layouts + includes + Sass → CSS)
5) Build artifacts (static HTML, CSS, JS, graph JSON)
6) Deployment targets (Netlify or GitHub Pages via GitHub Actions)
7) External services (Netlify CDN, GitHub repo)
b. Relationships & interactions
• Content store + _config.yml feed into Jekyll core
• Jekyll invokes custom plugins during the “generate” phase → outputs notes_graph.json and augments pages with backlinks
• Jekyll processes Sass → compiles CSS
• Layouts + includes template content → produce final HTML files
• Build artifacts get pushed to hosting (via Netlify CLI or GitHub Actions workflow)
• Hosting/CDN serves static assets to end users; graph JSON consumed by client-side graph visualization script
c. Architectural patterns & design principles
• Static-site generator pipeline: Clear separation of source content → build → deploy → serve
• Plugin-based extensibility: Ruby plugin scripts hook into Jekyll lifecycle events
• Modular theming: Reusable partials (_includes), layouts, Sass partials
• Content-centric design: notes organized in hierarchies, double-bracket linking, automatic graph data
d. Relevant technologies / frameworks
• Ruby & Jekyll core
• Custom Ruby plugins
• Liquid templating (layouts & includes)
• Sass (via Jekyll’s Sass converter)
• GitHub Actions (.github/workflows/jekyll.yml)
• Netlify (netlify.toml)