Add Parklife to your application's Gemfile and run bundle install.
Now generate a Parkfile configuration file and build script. Include some Rails- or Sinatra-specific settings by passing
--sinatra, create a GitHub Actions workflow to generate your Parklife build and push it to GitHub Pages by passing
$ bundle exec parklife init
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 Rails app:
# Load Parklife's Rails-specific integration which, among other things, allows # you to use URL helpers within the `routes` block below. require 'parklife/rails' # Load the Rails application, this gives you full access to the application's # environment from this file - using models for example. require_relative 'config/environment' 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_path(format: :atom) get sitemap_path(format: :xml) # A couple more hidden pages. get easter_egg_path, 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, see the Rails example's full build script for how you might do this.
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
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 shouldn't exist and is destroyed and recreated before each build. Defaults to
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.
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.