search

samvera / samvera.github.io

Public website for version controlled Samvera documentation (mostly Hyrax)
http://samvera.github.io
Apache License 2.0
7 stars 17 forks source link
core-components samvera-community

readme

samvera.github.io

Code: Build Status

Docs: Contribution Guidelines Apache 2.0 License

Community Support: Samvera Community Slack

What is samvera.github.io?

This project serves as the public website for version-controlled Samvera documentation (with a specific focus towards Hyrax).

Product Owner & Maintenance

samvera.github.io was a Core Component of the Samvera Community. Given a decline in available labor required for maintenance, this project no longer has a dedicated Product Owner. The documentation for what this means can be found here.

Product Owner

Vacant

_Until a Product Owner has been identified, we ask that you please direct all requests for support, bug reports, and general questions to the #dev Channel on the Samvera Slack._

Help

The Samvera community is here to help. Please see our support guide.

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:

To Test in Jekyll:

Basic Front Matter

The front matter on each page controls how the page is built and functions.

Example front matter for page Best Practices -> Coding Styles

---
title: "Coding Style with RuboCop"
permalink: best-practices-coding-styles.html
folder: samvera/best_practices/
sidebar: home_sidebar
keywords: ["Best Practices", "Coding Styles", "Rubocop"]
tags: [development_resources]
version:
  id: 'hyrax_1.0-stable'
last_updated: March 30, 2017
---

Front Matter Options

Notes on writing content

You can highlight content with the following...

<ul class='info'><li>This shows an info icon and provides the user additional information in a blue box.</li></ul>

info box (Example: code, webpage)

<ul class='warning'><li>This shows a warning icon and provides the user warning information in a red box.</li></ul>

warning box

<ul class='question'><li>This shows a question icon and provides the user with information in a yellow box indicating that there may be some uncertainty about a particular piece of information in the documentation.</li></ul>

question box

NOTE: You cannot use markdown in these boxes. For example, if you want a link, you will have to use an html anchor tag.

Browse pages

This site incudes a generated browse page. Each page's frontmatter keywords values are used to populate the browse by keyword page. The keywords should be written as titles, in upper and lower case, as they will be directly used as text on the page.

When changes are committed, the page needs to be regenerated and included with the committed changes. To build and save the revised browse_pages.html file:

Be sure to include the generated file in your pull request.

Versioning-information

The documentation on this site covers multiple gems and multiple versions of those gems. The recommended best practice is to specify the gem's name and version, including a link to the applicable branch in github. If there is documentation for multiple versions of the gem, then a selection list allows users to switch between versions.

Specifying gem name, version, and branch

Predefined version information

Common gems have version information encoded and can be referenced by id in front matter. The predefined version information is defined in _includes/version_info/

Example for Hyrax v1.0 stable:

version:
  id: 'hyrax_1.0-stable'
Custom version information

If the predefined version information does not exist. You can specify custom values in the front matter.

Example custom version information:

version:
  label: 'Hydra Role Management v0.2.2'
  branch:
    label: 'master'
    link: 'https://github.com/samvera/hydra-role-management'
Adding predefined version information for a gem version

It is good practice to add predefined version information, as this allows reuse and consistent encoding of gem names and versions.

Adding predefined version information is a two step process.

  1. Add the version information to a new version file in directory _includes/version_info/ naming the file with the gem and verion number (e.g. version_hyrax_1.0-stable.html). Include in the new file assignments for version_label, branch_label, and branch_link.

Example assignments for Hyrax v1.0:

{% assign version_label = 'Hyrax stable v1.0' %}
{% assign branch_label = '1.0-stable' %}
{% assign branch_link = 'https://github.com/samvera/hyrax/tree/1-0-stable' %}
  1. Add a new condition in _includes/versions.html that includes the predefined version information if its id is specified in front matter for a document. The condition in the case statement becomes the id that is used in front matter.

Example conditional include based on id:

{% case page.version.id %}
{% when 'hyrax_1.0-stable' %}
  {% include version_info/version_hyrax_1.0-stable.html %}
...
{% endcase %}

Selector for switching versions

Identifying multiple versions is done by specifying each version in front matter including its label and link. If the version is the active version that the current page is describing, then also include selected: 'true'. The multi-version information is repeated on every version's page for the documentation topic.

Example front matter for multiple versions:

version:
  versions:  
    - label: 'Hyrax 1.0'
      link:  'what-happens-deposit-1.0.html'
      selected: 'true'
    - label: 'Hyrax 2.0'
      link:  'what-happens-deposit-2.0.html'

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.

Contributing

If you're working on PR for this project, create a feature branch off of main.

This repository follows the Samvera Community Code of Conduct and language recommendations. Please do not create a branch called master for this repository or as part of your pull request; the branch will either need to be removed or renamed before it can be considered for inclusion in the code base and history of this repository.