-
Notifications
You must be signed in to change notification settings - Fork 10
Static Pages and Blog
The fulcrum.org project maintains static, informational web pages and a blog to promote the project to new users and clients. To manage these pages and the blog easily inside our rails application, we use Jekyll static site generator to build the static pages. While Jekyll is very well documented, in order to make Jekyll to work inside a rails application like Heliotrope, we've made a few changes to the standard Jekyll setup. The documentation below discusses our customization of Jekyll, specifically where things live, how to make changes to the static web pages of fulcrum.org, and how the static pages get built on deployment to staging, preview, or production.
.
├── Gemfile # uses 'jekyll' gem
├── config
│ └── jekyll.yml # configuration file for jekyll
├── fulcrum # the source for static pages, make changes here
│ ├── _posts # where blog posts go, authored in markdown
│ │ └── 2016-06-30-year-one-report.markdown # a blog post!
├── lib
│ ├── tasks
│ │ └── jekyll.rake # run be rake jekyll:build to auto regenerate site while working
├── public # the destination, where jekyll builds the static pages
All changes to static pages should be made within ./fulcrum/ while running the jekyll:build rake task. To do this, open a new terminal window and run
bundle exec rake jekyll:build
The site should build successfully and let you know it is watching ./fulcrum/ for any changes to files within that directory. Make changes to any files that need to be updated, or, if you are creating a new page, create the page and use an existing page's front matter as a template. For example, the page at http://fulcrum.org/about/ or ./fulcrum/about.html has a front matter that looks like the following:
---
layout: page
title: About
permalink: /about/
---
If you were creating a page called "Foo" that you wanted to live at http://fulcrum.org/foo/, you would call it foo.html in root of the ./fulcrum directory and give the file some front matter that looks like this:
---
layout: page
title: Foo
permalink: /foo/
---
Place the page content below the front matter using valid HTML. After you've made your additions, verify that the site re-built successfully. If it fails, Jekyll will let you know what went wrong in the terminal output.
If everything built successfully, check your work in the browser. If you haven't started the rails server up in your local environment yet, do it. Go to http://localhost:3000/foo/ and make sure it looks good. If you're satisfied, commit your changes and push to the remote repository.
The static pages are built during the Capistrano deploy process through a rake task that is configured in nectar:/hydra-dev/heliotrope-deploy/config/deploy.rb. So when you run something like
be cap staging deploy
After the app is updated, it will remotely run the following rake task within the application
bundle exec rake jekyll:deploy
and build the site into the ./public directory. If you were deploying to heliotrope-staging, the static pages would be built into /hydra-dev/heliotrope-staging/public/.