This document details our recommended processes to update current content, suggest changes to content, and fork content for your own use, as well as an introduction to how the content is organized and the tools we use to display content.
This repository was developed by the DataONE Community Engagement and Outreach Working Group and continues to be maintained by members of this team. Thank you for your interest in contributing to these educational materials.
Want to update a link or method? See a spelling error? Changes can be easily proposed by opening the GitHub Education page and editing content directly. For help, try this brief GitHub tutorial on forking and editing content.
masterbranch of this repository.
Check that the
title field of the YAML header (the first line of each
lesson) is in quotes.
Fork and edit content through GitHub, rather than editing privately, to enable others to use your edited content and to track how these materials are used.
All of the content is generated from markdown documents. These guidelines will walk you through the repository organization, the markdown basics, and any additional information.
The content linked to each tile on the home page is held within a single folder in the
best practices or
Each best practice can be found in the _bestpractices folder.
best practices are named for the first three words of their title, separated by hyphens. Instructions for creating new best practices can be found in the How to Write best practice example.
Teaching module are found in the folder called lessons, and each teaching module
lessons folder is called
XX is the order content is displayed via tiles on the home page, and
a brief description of the content. Edits can be made to the descriptive information contained in the
lesson_cover.md (the page that opens when a tile is selected on the home page). If education materials include slides, these slides are in a file called
slides.md. Do not use another filename. For example, the demonstration lesson markdown file can be viewed here. This demonstration lesson showcases most of the features you can use if publishing slides.
You are free to add other directories to your lesson. Images go in
images, and PDF files in
01_management/ index.md index.png images/ image1.png image3.jpg pdf/ one-pager.pdf
The markdown documents are rendered into a website using Jekyll. When sharing presentations, slides
themselves are rendered using remarkjs. The rendering is done using GitHub
pages, which builds the site from the
master branch. You can build the site
jekyll serve -w, and it will be available at
http://localhost:4000 for you to review.
The stylesheets are defined in
resources/styles, and rendered to
lessc (just type
make from the root).
A few hints for working with Liquid tags, which are the tags using in the templates.
Whitespace can be controlled by adding a
- to the opening and/or closing
liquid tag. e.g.
Would result in a newline being output, whereas:
List the available collections:
bestpractices lessons posts videos
The lesson collection is a bit odd because we need to treat each folder as an
item, but Jekyll treats each file as an item. Metadata from both the
index.md is used in rendering, but it takes a bit of extra
work to get those metadata attributes when rendering a page.
From the context of the index page, the slides page can be accessed as follows:
Similarly, from the slides page, the index can be accessed:
To get a list of tags used in a collection, include the
file using a liquid tag like:
where the value of the
the_collection property is the name of the collection
to evaluate. The list of tags will then be available as the
Thank you for your interest in making these data management education modules more useful!
In collaboration with the community, DataONE has developed high quality resources for helping educators and librarians with training in data management, including teaching materials, webinars and a database of best-practices to improve methods for data sharing and management.
If you have a question or concern, please open an Issue in this repository on GitHub.