Documentation Content Creation Guide

Table of contents

  1. About This Guide
  2. Platform Overview
  3. Docs Site Structure and Format
  4. Naming Conventions
  5. Adding and Editing Content
    1. Pushing changes to the site

About This Guide

This is a guide to migrating documentation to nypl.github.io/ami-preservation/. This guide assumes that users are familiar with GitHub and Markdown, but provides some basic resources and links for those who are not.

Platform Overview

The AMI Preservation Documentation Site is a static website. AMI staff will add documentation to the site via a repository on AMI Preservation’s GitHub that is designated for that set of documentation. A static site generator called Jekyll converts the raw text files that comprise the documentation (ie. Markdown files) to HTML, and the site files will be deployed to nypl.github.io/ami-preservation.

GitHub is a web-based hosting service that enables version-control of content, meaning that it records and saves the changes to files over time and enables users to recall specific versions of those files. Please refer to GitHub’s documentation guides for more information on Git and GitHub.

Docs Site Structure and Format

  • The site is hosted from the /docs directory of the ami-preservation repo.
  • Documents are written in GitHub Markdown
  • Documents that have children (sub-sections) must be contained within a directory.

Naming Conventions

  • All directories must be named using camelCase
  • All files must be named with dashes separating words: my-example.md

Adding and Editing Content

Pushing changes to the site

  • Only authorized administrators may push changes to the site.
  • To generate new content:
    • Commit changes to the master branch via GitHub
    • run bundle exec jekyll serve to generate new site files in user/ami-preservation/docs/_site