About This Site
- Git repository: https://github.com/EDIorg/data-package-best-practices
- All pages can be edited in markdown
- Served as gh-pages (from the docs dir)
- Contributions can be from many (via fork and pull request), moderated by a committee
- A very few pages of introductory material (including this page) and a navigation menu
- Based on a fork of http://bruth.github.io/jekyll-docs-template/
- Changes (after pushed to github) are public immediately
Best Practice sections
- Composed of multiple sections, each composed of multiple pages and moderated by the appropriate committee
- Each section is generated as a separate “book”, with R-bookdown (a wrapper for pandoc, in R)
- Edited pages do not become public until the book is rebuilt
- We use bookdown here to support these objectives:
- Pages can remain in development until they are explicitly posted, e.g., after moderation and build
- PDFs can be generated as needed for citable versions
- e.g., “Best Practices for EML metadata, V 4”, anticipated in early 2020
How to add new pages to the Index section
- Fork the repository
- Add a file to the
/docs/_postsdirectory. Since the template is blog-based, we follow the convention
- Option 1: do it manually and include the necessary front matter. Take a look at the source for this page to see how it works
- Option 2: use the script to generate an empty file with front matter. The advantage of using the script is that it automatically creates a soft link in the
_pagesdirectory without the date, which makes editing easier. If you want to control order, add the order to the front matter. Example:
bash-3.2$ ./bin/jekyll-page "About This Website" about
How to Link
Files are in markdown, which means you can include HTML. Use site tokens whenever possible. See Markdown Basics for more info.
link to a file:
<a href="/data-package-best-practices/files/966.pdf">link to 966.pdf</a>
link to an image: end of img.
Menu navigation is controlled by categories, labeled in the
_config.yml and assigned in each page’s front matter. We are currently using only two navigation sections:
tut, for BP-templates, how-tos for markdown,
about, general info on how this website is generated (this page).
_config.yml for the navigation sections (and other site-wide material, like tokens)
The major sections of this site are written in Markdown, and transformed to HTML with the R bookdown package.
Instructions for using bookdown can be found with other information for contributors, under “Using Bookdown”
Remember: each BP book is independent.