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

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: EDI logo 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).

See the _config.yml for the navigation sections (and other site-wide material, like tokens)

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.