docs-build

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).

Quick Start

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.

Usage

Adding or Removing Repositories

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

Theme

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.

Deployment

This site is intended to be deployed as an AWS Lambda which pushes updates to an S3 bucket from where they can be served.

Environment Variables

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_NAME
- BASE_PRIVATE_BUCKET_NAME
- BASE_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.

Documentation Repository Configuration

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
category: "collection development and management"
tags:
  - "policy"
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).

categories indicate what archival life cycle category(s) applies to the documentation. Categories enable filtering of documentation items on homepage. Values should be "collection development and management", "preservation", "arrangement and description", and/or "reference and outreach".

tags are used to describe what type of documentation the item is. Values should be either "policy" or "workflow".

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.

GitHub Action Configuration

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/sns-publish-topic@v1.6
      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.

Contributing

Pull requests accepted!

Authors

Hillel Arnold
Hannah Sistrunk
Katie Martin
Darren Young

License

This code is released under an MIT License.

RockefellerArchiveCenter / docs-build