/samvera.github.io

Public website for Dive Deeper into Hydra

Primary LanguageCSS

How Does This Work?

We use a Jekyll-based custom theme for markup and display, and pages are published to http://samvera.github.io.

Adding or Editing Content

These are community documents, so we rely on the pull request model. If you'd like to contribute content:

  • clone the project
  • make a branch
  • create/edit pages within the Hydra directory
  • add/update front matter
  • add links to the page in home_sidebar.yml
  • generate the A-Z Index, if needed
  • submit a Pull Request

Basic Front Matter

Example front matter for page Best Practices -> Coding Styles

---
title: "Coding Style with RuboCop"
permalink: best-practices-coding-styles.html
folder: hydra/how-to/best_practices/coding_styles.md
sidebar: home_sidebar
a-z: ['Coding Styles', 'Rubocop']
keywords: Best Practices
tags: [development_resources]
categories: How to Do All the Things
---

where,

  • title [String] - (required)_ - the title displayed on the generated html page
  • permalink [text] - (required) - the name of the generated html file that will be part of the url accessed by users
  • folder [text] - (required) - the location of this *.md file under the pages directory
  • sidebar [text] - (required) - value is always home_sidebar at this point
  • a-z [Array] - (recommended) - array of terms to link to this page in the A-Z Index
  • keywords [comma separated list] - (recommended) - keywords that get populated into the metadata of the page for SEO
  • tags [Array] - (recommended) - array of tags where tags must be defined in your _data/tags.yml list. You also need a corresponding tag file inside the pages/tags folder that follows the same pattern as the other tag files shown in the tags folder. It is rare that a new tag would be created. If you think you need a new tag, be sure to highlight it as requiring review in the issue.
  • categories [text] - (recommended) - represents the 4 major headings under which a page can reside

Generate the A-Z Index page

bundle exec jekyll build
mv generated/atoz.md pages

Then commit pages/atoz.md to github

Our Theme

We use a Jekyll theme designed for documentation. We chose the Documentation Theme because of its excellent navigation and clear page layout, and for the ease of working in markdown.