The blog of the Rockefeller Archive Center. This repository contains Markdown files and accompanying images for the site.
For organizational ease, your file should be named in the following format: YYYY-MM-DD-title-of-your-post.md.
All posts should be placed in the _posts directory. Refer to the directory structure of gh-pages if you have any questions about the post location.
All image files should be placed in the assets/img/ directory. You should also put the images in the correct Year/Month directory for your post's publication date. If those directories do not yet exist, create them or ask a member of the Digital Strategies team for help to create them.
Make sure your post links to the correct image files and includes alt text using the format: .
For example:
To include an image caption in the post, use: % include image.html dir="year/month/" file="image-file-name.png" description="caption text" %}. The description text will be the caption and the alt text for the image.
Example:
{% include image.html dir="2022/06/" file="related-collections-screenshot.png" description="Figure 2. Section of agent page in DIMES displaying links to related collections with search matches for that agents’ name." %}
Every post should include a section for front matter. The front matter of a post includes necessary metadata to help the blog theme display your post correctly and order it among other posts.
Below is an example of common front matter.
---
title: "Introducing the New Bits & Bytes"
date: 2019-01-02T11:10:00
author: Patrick Galligan
layout: post
categories:
- Bits & Bytes
- Software and Systems
tags:
- blogs
- technology
excerpt_separator: <!--more-->
---- Title: (Required) This should be the display title of your post. It will be the title that displays on the site. Titles which include characters like ampersands, colons, exclamation marks or slashes should be enclosed in double quotation marks, as in the example above.
- Date: (Required) The date that you are making your post public. It should be formatted like the above example. The date will control where in the list of posts your post will display.
- Author: (Required) The author or authors of the post. A single author should be on a single line, ex.:
author: Patrick Galligan. Posts with multiple authors should have each author on a separate line.author: - Patrick Galligan - Hillel Arnold
- Layout: (Required) The layout tells the theme how to format your post. It should always be
post. - Categories: (Optional) Associated categories for the post. Choose from existing categories whenever possible. A single category should be on a single line, ex.:
categories: Software and Systems. Posts with multiple categories should have each category on a separate line.categories: - Bits & Bytes - Software and Systems
- Tags: (Optional) Associated tags for the post. Choose from existing tags whenever possible. A single tag should be on a single line, ex.:
tags: blog. Posts with multiple tags should have each tag on a separate line.tags: - blogs - technology
- excerpt_separator: (Optional) The excerpt separator tells the theme how much preview text to show on the home page. Only include if you have included
<!--more-->at some point in your post Markdown, otherwise this will not work. If you do not use this field, the theme will automatically take the first 200 words of your post.
Create a new GitHub branch from the development branch. This is so we can track any changes and associate them with specific pull requests. You should name your branch YYYY-MM-DD-post. See the GitHub documentation on creating new branches if you have questions.
Place your files in the correct locations in your new branch (see "Post name and location" section above).
Once you have created a branch and placed your post file and images in the correct location you can open a pull request. You should create a pull request from your newly created branch which points at the development branch. See the GitHub documentation on creating pull requests if you have questions. Request review from another RAC staff member in the pull request.
Once another RAC staff member has reviewed and approved your pull request, you are ready to merge that pull request into the development branch. See the GitHub documentation on merging pull requests if you have questions.
Follow the steps outlined above to create a pull request from the development branch that points to the base branch, gh-pages. Then, merge that pull request into the gh-pages branch. This will automatically publish the post, so only merge when you are ready for your post to be visible to the world. By pushing your post to the development branch first, you are able to preview the text before it is published to the website.
In order for Markdown tables to render properly, they need to be separated from other block-level elements. This means you should add a blank line before and after a table in order for it to render properly.
Download the repository to your local machine using git:
git clone https://github.com/RockefellerArchiveCenter/bits_and_bytes.git
Move into the main directory of the repository
cd bits_and_bytes
Install dependencies
bundle install
Run the development server
bundle exec jekyll serve
You'll see some messages appear, and should be able to view the site in a web browser at http://localhost:4000/
The repository includes BackstopJS to test visual changes to the site by comparing a set of reference images for different screen sizes. Anytime the CSS styles are changed, use BackstopJS to test locally:
- Install BackstopJS dependency:
yarn install - Build and run the site using the steps in the Local Development section above.
- Run Docker.
- In another terminal, run the BackstopJS tests:
yarn backstop-test. - Review the results in the browser and look at the diff of any failed tests.
- To update the reference image files with the results of the last test images use:
yarn backstop-approve. Subsequent tests will be compared against these updated reference files. - Commit any updated reference images to the repository so that future tests will be compared against the most recent images.
To add or update reference images, edit the scenarios in backstop.json and run yarn backstop-reference.
Bits & Bytes is released under an MIT License.
Bits & Bytes content is released under a CCBY 4.0 License.