How leandropa/natile works
Project type and purpose
• This is an open-source, Ruby-based static site generator that produces a fully customized LinkTree-style page and deploys it on GitHub Pages.
• It reads a YAML config, loads plugins to fetch dynamic values (e.g., Medium followers, GitHub stars), applies a theme, and emits a static site.
File structure
• Top-level files:
• Gemfile/Gemfile.lock – Ruby dependencies for the generator
• scaffold.rb – the generator’s entry point
• config.yml – site configuration and plugin settings
• Makefile & deploy.sh – local build/deploy helpers
• .github/workflows/build.yml – CI/CD pipeline for automatic builds
• Directories:
• plugins/ – plugin classes implementing a common interface (Plugin.rb)
• themes/ – each theme has HTML template, CSS, JS, and assets
• _output/ – auto-generated static output (do not edit)
README insights
• Confirms features: plugin extensibility, theme swapping, GitHub Actions–driven automatic redeployment, GitHub Pages hosting.
• Shows how config.yml drives everything, and how plugins inject dynamic data.
Main components and interactions
a. Components
• Developer/Repository – user pushes code and config to GitHub repo
• CI/CD (GitHub Actions runner) – triggers on schedule or push
• Generator Engine (scaffold.rb + plugins)
• Plugins – fetch external data from:
– GitHub API
– Medium API
• Config (config.yml) – supplies theme choice, site data, plugin settings
• Themes/templates – HTML, CSS, JS assets under themes/default (or custom theme)
• Output (_output) – generated static pages
• Hosting (GitHub Pages) – serves the gh-pages branch (static site)
• End Users – browse the live site
b. Relationships & data flows
1. GitHub Push or Scheduled Trigger → GitHub Actions
2. Actions Runner
• Checks out code
• Installs Ruby gems (Gemfile)
• Runs scaffold.rb
3. scaffold.rb
• Loads config.yml → passes settings to generator
• Loads each plugin (plugins/*.rb) → each plugin calls its external API → returns dynamic data
• Reads theme templates (themes/<theme>/index.html, CSS, JS)
• Renders HTML pages, injecting both static config data and plugin outputs
• Writes generated files into _output/
4. Actions Runner
• Commits/switches to gh-pages branch
• Copies _output/ contents
• Pushes to remote gh-pages
5. GitHub Pages
• Detects changes on gh-pages branch → serves the static site
6. End User
• Requests the URL → GitHub Pages returns the static HTML/CSS/JS
c. Architectural patterns & design principles
• Plugin Pattern – loose coupling of dynamic-data providers via a common Plugin interface
• Template-based static site generation
• CI/CD as infrastructure – automated, scheduled or on-push builds
• Separation of concerns – configuration, data fetching, templating, and deployment are distinct
d. Key technologies/frameworks
• Ruby & Bundler (Gemfile) – runtime for scaffold script
• GitHub Actions – CI/CD and scheduled redeploys
• YAML – config format (config.yml)
• HTML/CSS/JS – theming assets under themes/
• GitHub Pages – hosting platform
Be detailed, but don’t over-compartmentalize
• Piece: code, config, data-fetch, template, output, CI, hosting, external API.
• How new plugins or themes plug into the system.