NRRD flavored 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
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:
---
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:
- 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_displayspecified, it will default to usingtitle. -
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 andpermalink, 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
listandhash. In order for this to work, it must be accompanied by thenav_itemsattribute list. -
nav_items (optional): An attribute list where each item contains a
name,title, andsubnav_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_itemsattribute. Similar to its parent, eachsubnav_itemshas anameandtitleattribute.
---
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
---
- Add a
<h1>,<h2>, or<h3>tag (or equivalent markdown) with text that matches thenameproperty of anav_itemspecified 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
- Explicitly add an id to that tag. This could be useful if the text content of your header is cumbersome, or if the
nav_itemthat 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>
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
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