-
Notifications
You must be signed in to change notification settings - Fork 9
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 (like most Jekyll projects, we do not track changes on Jekyll's output folder, in our case the ./public folder).
Adding a blog post is relatively straightforward. The easiest method is to duplicate a post file contained in /fulcrum/_posts/ and rename it using the current date and title of the post. For example:
2018-10-16-announcing-editoria-integration-plans.markdown
Modify the YAML front matter for the blog post to include the title, post author, and publication date. It is important that the publication date is not set in the future, otherwise Jekyll will not build the post.
The post should be written in a mix of markdown and HTML, with the majority of the syntax in markdown.
Most likely, you will only need to use HTML when inserting images within the post. This post is a good example of how images should be marked up within a post. Note that adding a class="responsive-img" to the <img> element will help create a responsive image that resizes with the browser.
Image files should be placed in /fulcrum/img/blog/ and their filenames should correspond with the date of the blog post file. For example, blog post 2018-08-01-humanities-ebook-launches.markdown includes images with filenames like 2018-08-01-heb-catalog.jpeg.
If you want to set a feature or lead image for a post (see example) you can do so by adding basic YAML front matter that includes the filename, alt text, and image caption. For example:
---
layout: post
title: "Tools fit for purpose: Gabii on Fulcrum"
date: 2018-04-05 06:46:30 -0400
author: Charles Watkinson
categories: blog
feature-image-file: "2018-04-05-gabii-on-fulcrum.png"
feature-image-alt: "Screenshot of Gabii on Fulcrum showing an e-book and 3D model side-by-side in browser"
feature-image-caption: "March 2018 marked the launch of A Mid-Republican House from Gabii–an interactive publication with 3D model."
---
Once you've created the blog post, run bundle exec rake jekyll:build and then look at your localhost to see if the post was built properly. If all looks well, follow the usual Git workflow to add, commit, push and issue a PR for your work. The post will be live on production with the next release and deployment.
If the post needs be released immediately, you will have to follow a hotfix Git workflow to base your branch of the last tagged release, cut a new release, and deploy that newly tagged release to production.
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/. Just like when you ran the jekyll::build task locally, if you Jekyll has any problems building the site during deployment, you'll see errors in the console. However, you should rarely run into this problem if you followed the steps above and already tested running the rake task locally.