Welcome to your new Sitepress site! If you know Rails, you'll feel right at home in Sitepress because it's built on top of Rails. There's a few things you'll need to know to get around:
First thing you'll want to do is start the preview server:
$ sitepress server
Then open http://127.0.0.1:8080 and you'll see the welcome page.
To specify a layout for a page, add a layout
key to the pages frontmatter. For example, if I create the layout tech-support
, I'd add the following frontmatter to the top of a page in pages/support/router.html.md
:
---
title: How to fix a router
layout: tech-support
---
# How to fix a router
1. Unplug the router.
2. Plug in the router.
Sitepress will look for the layout in the layouts
folder from the layout
key in the file's frontmatter.
Additionally, you may use the render_layout
function in a page, or layout, to nest the layouts. For example, you could:
---
title: How to fix a scanner
---
= render_layout "tech-support" do
%h1 How to fix a scanner
%ol
%li Unplug the scanner.
%li Plug in the scanner.
The render_layout
can be used to nest a layout within a layout, which is a very powerful way to compose content pages.
Like Rails, Sitepress organizes files in certain directories:
-
pages
- This is where you'll edit the content. Allerb
,haml
, andmd
files will be rendered and all other files will be served up. Support for other templating languages should work if you add them to the Gemfile and they already work with Rails. -
layouts
- Layouts for all pages may be found in this directory. Layouts are great for headers, footer, and other content that you'd otherwise be repeating across the files inpages
. -
helpers
- Complex view code that you don't want to live inpage
orlayouts
can be extracted into helpers and re-used throughout the website. These are just like Rails helpers. -
assets
- If you want Sprockets to fingerprint and manage images, stylesheets, or scripts then put them in theassets
directory. -
config
- All configuration files and initializers belong in this directory. Theconfig/site.rb
file has settings that can be changed for the Sitepress site. Changes made to this file require thesitepress server
to be restarted.
Once you're satisfied with your website and you're ready to compile it into static HTML files, run sitepress compile
and the website will be built to ./build
.
Anything you can do in Rails, you can do in Sitepress. If you find yourself needing more Rails for Sitepress, you could try adding it to the Gemfile
and integrating it into your website. You can also embed and integrate Sitepress into a full-blown Rails app and serve up the content without statically compiling it.
Check out https://sitepress.cc for the latest and most up-to-date Sitepress documentation.