SLIM STATIC

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.

Usage

1. Install dependencies with bundle

2. Run Guard with guard. You can alternatively just run ruby build.rb manually.

3. Run a static HTTP server e.g. python -m http.server -d dist (then open localhost:8000). You can alternatively run sh server.sh which does the same thing.

4. Add Slim files in src/pages/. Files in src/pages/ will be copied to the top level of dist/. This includes folder structure, e.g. src/pages/subfolder/foo.slim would get copied to dist/subfolder/foo.html. Slim files outside of pages/ 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 a src/shared folder as shown below.

5. 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 through PartialData.

   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 inside src for this purpose.

6. 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.

Notes

• 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 install pandoc to your system as well.

Github Actions automation.

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