Parklife

Parklife is a Ruby library to render a Rack app (Rails/Sinatra/etc) to a static site so it can be served by Netlify, Now, GitHub Pages, S3, or another static server.

Getting started

Add Parklife to your application's Gemfile and run bundle install.

gem 'parklife'

Now generate a Parkfile configuration file and build script. Include some Rails- or Sinatra-specific settings by passing --rails or --sinatra, create a GitHub Actions workflow to generate your Parklife build and deploy it to GitHub Pages by passing --github-pages.

$ bundle exec parklife init

How to use Parklife

Note

See the parklife-rails repository for how to use Parklife with Rails.

Parklife is configured with a file called Parkfile in the root of your project, here's an example Parkfile for an imaginary Rack app:

# Assuming your Rack app lives in ./app.rb:
require_relative 'app'

Parkfile.application.routes do
  # Start from the homepage and crawl all links.
  root crawl: true

  # Some extra paths that aren't discovered while crawling.
  get '/feed.atom'
  get '/sitemap.xml'

  # A couple more hidden pages.
  get '/easter_egg', crawl: true

  # Services typically allow a custom 404 page.
  get '/404.html'
end

Listing the routes included in the above Parklife application with parklife routes would output the following:

$ bundle exec parklife routes
/             crawl=true
/feed.atom
/sitemap.xml
/easter_egg   crawl=true
/404.html

Now you can run parklife build which will fetch all the routes and save them to the build directory ready to be served as a static site. Inspecting the build directory might look like this:

$ find build -type f
build/404.html
build/about/index.html
build/blog/index.html
build/blog/2019/03/07/developers-developers-developers/index.html
build/blog/2019/04/21/modern-life-is-rubbish/index.html
build/blog/2019/05/15/introducing-parklife/index.html
build/easter_egg/index.html
build/easter_egg/surprise/index.html
build/index.html
build/location/index.html
build/feed.atom
build/sitemap.xml

Parklife doesn't know about assets (images, CSS, etc) so you likely also need to generate those and copy them to the build directory.

More examples

Take a look at the parklife-rails example app, and the Rack and Sinatra working examples within this repository.

Configuration

Linking to full URLs

Sometimes you need to point to a link's full URL - maybe for a feed or a social tag URL. You can tell Parklife to make its mock requests with a particular protocol / host by setting its base so Rails *_url helpers will point to the correct host:

Parklife.application.config.base = 'https://foo.example.com'

The base URL can also be passed at build-time which will override the Parkfile setting:

$ bundle exec parklife build --base https://benpickles.github.io/parklife

Dealing with trailing slashes (turning off nested index.html)

By default Parklife stores files in an index.html file nested in directory with the same name as the path - so the route /my/nested/route is stored in /my/nested/route/index.html. This is to make sure links within the app work without modification making it easier for any static server to host the build.

However, it's possible to turn this off so that /my/nested/route is stored in /my/nested/route.html. This allows you to serve trailing slash-less URLs with GitHub Pages or with Netlify by using their Pretty URLs feature or with some custom nginx config.

Parklife.application.config.nested_index = false

Changing the build output directory

The build directory's contents are removed before each build. Defaults to build.

Parklife.application.config.build_dir = 'my/build/dir'

Handling a 404

By default if Parklife encounters a 404 response when fetching a route it will raise an exception (the :error setting) and stop the build. Other values are:

• :warn - output a message to stderr, save the response, and continue processing.
• :skip - silently ignore and not save the response, and continue processing.

Parklife.application.config.on_404 = :warn

Setting the Rack app

If you're not using the Rails configuration you'll need to define this yourself, see the examples.

Parklife.application.config.app

License

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

Code of Conduct

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