A really easy static site generator using Slim and Guard.
I made this because there wasn't a dead-simple way to make a static HTML site using partials (shared HTML snippets). HTML5 imports are unfortunately not gonna happen, the powers that be decided on ES modules. Which are okay, but I don't want to write a bunch of createElement
or create HTML in Javascript by other means. Also, being able to use Slim would be a nice plus.
-
Install dependencies with
bundle
-
Run Guard with
guard
. You can alternatively just runruby build.rb
manually. -
Run a static HTTP server e.g.
python -m http.server -d dist
(then openlocalhost:8000
). You can alternatively runsh server.sh
which does the same thing. -
Add Slim files in
src/pages/
. Files insrc/pages/
will be copied to the top level ofdist/
. This includes folder structure, e.g.src/pages/subfolder/foo.slim
would get copied todist/subfolder/foo.html
. Slim files outside ofpages/
won't be copied to the output at all. However, they can still be used as build-time, e.g. you can put partials inside asrc/shared
folder as shown below. -
Include partials using the
partial
helper (make sure to use the double equals==
so nothing gets escaped). You can also pass custom data to the partial and then read it throughPartialData
.body == partial("./src/shared/nav.slim") == partial("./src/shared/other_partial.slim", { custom_arg: "foo" })
# in other_partial.slim = PartialData[:custom_arg]
Note that you don't have to use the exact folder name
src/shared
, you can use any custom folder name insidesrc
for this purpose. -
Put static assets in
src/public
. These will be copied as-is, including folder structure.
... and that's about it. The Guard process will watch for all changes to the src
directory, and rebuild dist
each time. You do have to press reload in your browser.
-
Slim supports writing inline CSS, Javascript, Sass, Coffeescript, and so on. That's why there's no support for these kinds of standalone files. See https://rdoc.info/gems/slim/frames#embedded-engines-markdown
-
If you want to use the
markdown
preprocessor, you need to installpandoc
to your system as well.
Personally, I don't like to have to run build
on my local system. It's too much work. I'd rather be able to edit files directly on Github and then have them automatically deployed. However, since source files are written in .slim, some preprocessing is required. That's why I wrote a Github Actions script.
If you add this to your repo at .github/workflows/ruby.yml
, then when you push to master, it will automatically run ruby build.rb
(with Pandoc support) and deploy the result to the gh-pages
branch (which Github will automatically deploy):
# This workflow uses actions that are not certified by GitHub.
# They are provided by a third-party and are governed by
# separate terms of service, privacy policy, and support
# documentation.
# This workflow will download a prebuilt Ruby version, install dependencies and run tests with Rake
# For more information see: https://github.com/marketplace/actions/setup-ruby-jruby-and-truffleruby
name: Ruby
on:
push:
branches: [ master ]
permissions: write-all
jobs:
build:
runs-on: ubuntu-latest
strategy:
matrix:
ruby-version: ['3.0']
steps:
- uses: actions/checkout@v3
- name: Setup Ruby
uses: ruby/setup-ruby@v1
with:
ruby-version: ${{ matrix.ruby-version }}
bundler-cache: true # runs 'bundle install' and caches installed gems automatically
- uses: nikeee/setup-pandoc@v1
- name: Build
run: bundle exec ruby build.rb
- name: Deploy
uses: s0/git-publish-subdir-action@develop
env:
REPO: self
BRANCH: gh-pages # The branch name where you want to push the assets
FOLDER: dist # The directory where your assets are generated
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # GitHub will automatically add this - you don't need to bother getting a token
MESSAGE: "Build: ({sha}) {msg}" # The commit message