Theme file along with a Python script which retrieves updates for documentation repositories, and builds internal and external-facing sites. Requires at least one documentation repository (see processing-manual).
A Dockerfile for local development (Dockerfile-local) is included in this repository so you can quickly spin up a sample site on your computer. With git and Docker installed, run:
git clone https://github.com/RockefellerArchiveCenter/docs-build.git
docker-compose build
docker-compose up
The public docs site (which includes all the repositories listed under the public
key in repositories.yml) will be available in your browser at http://localhost:4000.
Repositories can be added or removed from either the public or private site by
updating repositories.yml. Only the sites listed under the public or private
key will be built for each site, so make sure to add publicly-available Repositories
to both the public and private lists.
You will also need to make sure the repositories have some necessary configuration files:
- Jekyll configuration files (see Documentation Repository Configuration)
- GitHub Actions file to publish update notifications to AWS Simple Notification Service (SNS) (see GitHub Action Configuration)
Last, you will need to ensure that the repository has access to the following Organization Secrets in Github:
- AWS_DOCS_ACCESS_KEY_ID
- AWS_DOCS_ACCOUNT_ID
- AWS_DOCS_REGION
- AWS_DOCS_SECRET_ACCESS_KEY
- AWS_DOCS_SNS_TOPIC
The site uses a Jekyll-based theme to create a cohesive structure and
customizable interface. These files are located in the theme/ directory.
Layouts are written in HTML and are chiefly composed from a separate directory of Jekyll-based includes and one default layout template. They are styled with both Bootstrap and custom CSS and are rendered with the Liquid template language.
The layout directory formats the various documentation files stored in the individual GitHub repositories and thereby creates the site's central interface for access to documentation. This process is achieved through the use of layout variables in the documentation files' YAML front matter.
This site is intended to be deployed as an AWS Lambda which pushes updates to an S3 bucket from where they can be served.
The following environment variables must be present in order for this deployment pattern to work effectively:
GH_TOKEN- a GitHub Personal Access Token which has the necessary permissions to clone private repositories. Make sure this has the scope org:read as well.GH_SECRET- a secret key associated with the GitHub Webhook.- Environment variables for S3 buckets to which files will be uploaded. These
should be formatted as {BRANCH}_{AUDIENCE}_BUCKET_NAME:
DEVELOPMENT_PRIVATE_BUCKET_NAMEBASE_PRIVATE_BUCKET_NAMEBASE_PUBLIC_BUCKET_NAME
REGION_NAME- the AWS region in which the S3 buckets are located.ACCESS_KEY- an Access Key for an IAM user that has the necessary permissions to upload files to the bucket.SECRET_KEY- the Secret Key for an IAM user with the necessary permissions to upload files to the bucket.
In order to build the full documentation site, the following variables must be
available in a file named _config.yml located the root directory of each
documentation repository. These files should be valid YAML.
public: true
title: "Collection Policy"
description: "The main collecting areas of the Rockefeller Archive Center."
pages:
- ["Rockefeller Archive Center Collection Policy", "index"]
public indicates whether or not the documentation should be public. Values
should be either true or false (booleans, not strings).
title is the official title of the documentation, which will be displayed on
the home page of the site.
description is a statement of what the documentation is. This text will become the description meta tag for the site, which is displayed in search-engine results, so keep it short and snappy.
pages is a list of lists of the pages included in this site. The first value
in each list is the name, and the second is the filename of the page (without the
extension). These values are used when building tables of contents.
Other variables can be included in this config file if desired.
In order to deliver update notifications to Amazon SNS (which will trigger a build of the site), a GitHub Actions file named .github/workflows/publish_sns.yml needs to be created and populated with the following content:
name: Publish to SNS
on:
push:
branches:
- base
- development
# Allows you to run this workflow manually from the Actions tab
workflow_dispatch:
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Publish SNS Notification
uses: nothingalike/[email protected]
with:
MESSAGE: ${{ toJSON(github) }}
TOPIC_ARN: "arn:aws:sns:${{ secrets.AWS_DOCS_REGION }}:${{ secrets.AWS_DOCS_ACCOUNT_ID }}:${{ secrets.AWS_DOCS_SNS_TOPIC }}"
env:
AWS_REGION: ${{ secrets.AWS_DOCS_REGION }}
AWS_ACCESS_KEY_ID: ${{ secrets.AWS_DOCS_ACCESS_KEY_ID }}
AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_DOCS_SECRET_ACCESS_KEY }}
To test this configuration, you can trigger a workflow run from the GitHub interface.
The repository includes BackstopJS to test visual changes to the site theme 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 Quick Start section above.
- 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.
Pull requests accepted!
Hillel Arnold Hannah Sistrunk Katie Martin Darren Young
This code is released under an MIT License.