NRRD flavored markdown - DOI-ONRR/nrrd GitHub Wiki

Site supported markdown

Natural Resources Revenue Data (NRRD) uses kramdown for its markdown syntax.

kramdown was chosen because it supports footnotes, which are used frequently throughout the site

Jekyll front matter

NRRD is powered by the static generator, Jekyll. At the heart of Jekyll is the ability to assign 'front matter' to an HTML page to specify routing information, or provide information that informs the unique layout of that page. Jekyll front matter is easy to spot. It appears at the top of the page in files with the .md or .html file extensions, and looks like this:

---
title: Some title
permalink: /some-route/
layout: content
---

Front Matter attributes contain key-value pairs

---
key: value
---

or lists with multiple items

---
key: 
  - 1st item, 1st attribute
    1st item, 2nd attribute
  - 2nd item, 1st attribute
    2nd item, 2nd attribute
---

Attributes should not be left blank, like below. Include them with a value, or not at all.

---
key:
---

Content pages

A NRRD 'content' page is a page that has the layout set to content, such as in the example above.

For example, the Federal Production Downloads page has this front matter:

---
title: Federal Production | Documentation
title_display: Federal Production by Location
layout: content
permalink: /downloads/federal-production/
breadcrumb:
  - title: Downloads
    permalink: /downloads/
---

In this example, because the front matter contains layout: content, Jekyll knows to generate a breadcrumb using the title_display and breadcrumb attributes, and we end up with something like this:

Example of Title and Breadcrumb

Available attributes

  • layout: should be set to 'content' for all content pages.
  • title: text that displays in the site <head>. It is visible in your browser tab or when a page appears as an embedded link.
  • title_display (optional): The page title visible on the top of the content. If there is no title_display specified, it will default to using title.
  • breadcrumb (optional): The breadcrumb is an indicator of which section of the site a particular page is in. It has two attributes, title, for display text and permalink, for the associated link.
  • permalink: the relative file path to that page. For example, if you were creating a page that could be found at https://example.com/page/one/, the permalink would be /page/one/. Make sure to end and begin with a / to avoid routing issues.
  • resource (optional): This attribute is used in the Case Studies pages to create an associated resource icon.
    • Only include for Case Studies pages
    • On Case Studies pages that are resource agnostic, specify default.
  • selector (optional): Including the selector field will add a subpage navigation panel to the layout. Options include list and hash. In order for this to work, it must be accompanied by the nav_items attribute list.
    • list: Creates a sticky navigation list on the right side of the page. Example.
    • hash: Creates a sticky navigation dropdown on right side of the page. Example.
  • nav_items (optional): An attribute list where each item contains a name, title, and subnav_items. The nav items specified will link to sections on the same page. There are a few ways to do this explained below.
  • subnav_items (optional): An attribute list nested within the nav_items attribute. Similar to its parent, each subnav_items has a name and title attribute.

nav_items front matter structure:

---
nav_items:
  - name: some-name
    title: Display text
  - name: some-other-name
    title: Display text
    subnav_items:
      - name: subtitle-name
        title: Subtitle name
      - name: second-subtitle-name
        title: Second subtitle name
---

Connect the nav_items or subnav_items to content on the page:

  1. Add a <h1>, <h2>, or <h3> tag (or equivalent markdown) with text that matches the name property of a nav_item specified in the yml frontmatter. Jekyll will render the heading tag with an id that is a lowercase and snake case version of the text content of that heading. <h2>Nav item name</h2> will become <h2 id="nav-item-name">Nav item name</h2>, for instance.
<h2>Nav item name</h2>
## Nav item name
  1. Explicitly add an id to that tag. This could be useful if the text content of your header is cumbersome, or if the nav_item that you are creating is not a heading tag. For example:
<h2 id="heading-text">Heading text that is really long</h2>

<a href="#" id="whatever">Whatever</a>

Emphasize a paragraph

Blockquotes do not function normally in NRRD content pages. In both Github-Flavored Markdown or kramdown, using blockquote syntax (>) generates a blockquote, so that this

> Example blockquote
>
> that has two lines

becomes this:

Example blockquote

that has two lines

In NRRD content pages, using blockquotes creates larger text with added spacing. It is best used at the top of pages, such as here

Add footnotes

To add footnotes, simply add [^] (along with some identifier) to the end of a sentence. You can then reference it by recalling that same identifier with its associated footnote text. More documentation

Paragraph text. La da da da.[^1] I bet we could even fit two in here.[^second]

...

### Footnotes

[^1]: Associated text
[^second]: Associated text
⚠️ **GitHub.com Fallback** ⚠️