About This Site

Warning

The documentation on this particular page is out of date. We are transitioning to a Quarto site and will revise soon.

General

  • 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

Section organization

Index section
  • 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

DPBP layout

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

Instructions

Index section

How to add new pages to the Index section
  1. Fork the repository
  2. Add a file to the /docs/_posts directory. Since the template is blog-based, we follow the convention YYYY-MM-DD-name-of-post.md
    1. 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
    2. 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 _pages directory 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

BP sections:

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.