Hotpages

Hotpages is currently in pre-release. There are likely many bugs, but please try it if you're interested. Feedback welcome here

[ 日本語 ]

Static website authoring with Ruby.

Hotpages is a static site generator using Ruby. It's especially recommended when you want to create sites by hand-coding HTML while using Ruby to keep your HTML DRY (Don't Repeat Yourself).

Features

• File-based routing. The file structure under the pages directory is directly output as the website structure.
• Helper functions similar to Rails ActionView
• ERB as the primary template language, with support for many templates via Tilt
• Default support for Hotwire (Turbo, Stimulus)
• Comfortable website authoring with a development server featuring hot reload
• Built-in features useful for static site building, including i18n, asset cache busting, broken internal link detection, template path annotations, and inline SVG

Roadmap to Version 1.0.0 Release (Planned)

• Core functionality
• Polish core functionality
• Expand unit tests
• Documentation and RBS preparation
• Add model utility classes. Planning to add classes for handling Markdown files

Installation

Hotpages requires Ruby 3.4 or later and bundler.

If you use rbenv to install Ruby, refer to Installing rbenv and Installing Ruby versions.

Run the following command to verify Ruby is installed correctly. If it looks OK, proceed.

ruby -v # OK if it shows version ruby 3.4 or later

Once Ruby is installed, install bundler. After both Ruby and bundler are installed, proceed.

gem install bundler

The Hotpages gem is not yet published to a registry, so clone the Git repository and install from it as follows:

git clone https://github.com/koedasha/hotpages.git

Get Started

In the directory where you cloned the repository, run the following command to create a new Hotpages site. Replace YOUR_NEW_SITE_NAME with your new site’s name.

hotpages/exe/hotpages new YOUR_NEW_SITE_NAME

Start the development server for the new site with:

cd YOUR_NEW_SITE_NAME
bundle install
bin/dev

Open http://localhost:4000 in your browser. If you see Hello, hotpages!, you’re all set!

Stop the development server with C-c.

Finally, generate the static site by running:

bin/gen

By default, the output is written to the _site directory in the current directory.

Edit Web Pages

Continuing from “Get Started,” open pages/index.html.erb under site directory in your editor. You should see <%= greeting %> in the file. greeting is a simple Ruby method defined in pages/index.rb.

Try changing the return value of the greeting method in pages/index.rb. Thanks to the hot reloading freature of development server, the text shown in your browser should update immediately.

The basic approach is to place template files and Ruby files that handle their data under the pages directory to define web pages. You can freely organize files under pages.

This directory structure directly becomes the structure of the pages in the generated site.

Each Ruby file defines a subclass of the Page class described in shared/page.rb. By modifying this Page class, you can provide methods common to all pages.

Ways to Define Pages

Pages without Ruby

A template alone will be compiled into a web page. If you don’t need a Ruby file, you don’t have to create one.

Pages with Ruby only

If you define a body method in the Ruby file, its return value is evaluated as ERB and compiled into the page’s HTML.

Directory-wide shared Ruby file

If you want a shared Ruby file within a directory, place _page.rb in that directory. Its contents are applied to all templates in that directory.

Ignored files under pages

Files placed under pages whose names start with an underscore (_) are ignored and not compiled into web pages.

Path expansion

Directories and page files whose names start with a colon, such as :slug.html.erb, are treated as expandable paths. The expansion names are taken from the return value of the self.segment_names method defined in a Ruby file with the same basename (without the extension) in the same directory, such as :slug.rb. For example, if self.segment_names in :slug.rb returns an array like ["one", "two"], then :slug.html.erb will generate two HTML files: one.html and two.html.

In this case, the expanded segment string, such as one or two, is stored in the segments hash within the page file. If the page filename is :slug.html.erb, you can access it as segments[:slug].

Partial rendering

Use the render method to render partials while passing local variables, for example render "shared/post", post: post. You can place partials under the pages directory and specify the partial file from a page using a relative path. In this case, the partial filename must begin with an underscore (_); see Ignored files under pages.

Directories in site Overview

• pages
  • The most important directory. Place the page files described above.
• models
  • Place model files. By calling models from page Ruby, you can author web pages with a workflow similar to building an MVC application.
• data
  • Place data files to be used by models. Intended for CSV, Markdown, etc.
• helpers
  • Place helper modules callable from pages. Helper functions are available globally within pages.
• layouts
  • Place layout files. From page Ruby, use layout "layout_file_name" to change the layout. The default layout file is site.html.erb.
• shared
  • Place Ruby files and partials shared across pages.
• assets
  • Place JavaScript, CSS, and images. By default, controllers contains Stimulus controller JS, css contains CSS, and images contains images.
• locales
  • Locale files for i18n. By default, localization uses FastGettext YAML locale files.

Templates Other Than ERB

Hotpages supports ERB by default, but any format supported by Tilt should be usable. See the Tilt README for supported template engines. To use them with Hotpages, install the necessary library and require it in site.rb. For example, to render Markdown with Kramdown:

bundle add kramdown

# site.rb
require "kramdown"

This enables handling template files and partials like pages/index.html.md (the topmost extension of the template file must indicate the output file format).

There are many template engines supported by Tilt, so not all have been tested. If you encounter issues with a template you use, please send feedback.

Websites Built with Hotpages

• Koeda-sha's Website

  Hotpages was extracted from this site.

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/koedasha/hotpages. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

The gem is available as open source under the terms of the ISC License.

Code of Conduct

Everyone interacting in the GemTemplate project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.