This page demonstrates the Markdown features available with this theme’s current Kramdown, GFM-input configuration. It covers document structure, text, links, images, lists, tables, and Kramdown extensions. Each example separates its rendered output under an Example subheading from the Markdown source shown in a note box. Equivalent punctuation variants are included where useful; this is a feature reference rather than a catalogue of every parser edge case.

You can combine these features with the theme’s layout blocks. Ordinary Markdown needs no layout classes. The source examples use an alert class only to style their code containers; you do not need that class in your own content.

Headings
Heading IDs
Paragraph
Inline text formats
Block quote
Fenced code block
Footnotes
Lists
- Ordered list
- Unordered list
- Task list
- Lists with paragraphs and code
Horizontal rule
Definition list
- Longer definitions
Link
Image
- Linked image
Reference-style links and images
Table
Abbreviations
Escaping characters and HTML entities
Automatic contents lists
Attribute lists and reusable attributes
Separating adjacent blocks
Parser comments and literal content
HTML alongside Markdown
Features requiring additional support

The contents list above is generated from this page’s headings. See Automatic contents lists for its source.

Headings

Headings organise the page into sections and subsections. Start a heading with one to six # characters followed by a space; more characters create a lower heading level. The theme supplies the page title, so normally begin body sections with ## and keep the heading hierarchy in order.

Example

Heading 1

Heading 2

Heading 3

Heading 4

Heading 5

Heading 6

# Heading 1

## Heading 2

### Heading 3

#### Heading 4

##### Heading 5

###### Heading 6

Heading IDs

A heading ID gives a section a stable link destination. Add {#your-id} after the heading text, then link to it with #your-id. Choose a unique ID without spaces; ordinary headings also receive automatically generated IDs. For a custom ID, the small chain-link button appears when you hover over the heading or focus the button with the keyboard. Activate it to copy the full section URL; a brief “Copied” message confirms success and is also announced to screen readers.

Example

Heading with an ID

Return to the Link section.

## Heading with an ID {#custom-id}

[Return to the Link section](#link-section).

Paragraph

Paragraphs group related sentences. To start a new paragraph, leave a blank line after the preceding text, then write the next paragraph. No special marker is needed. Ordinary line breaks in the source stay within the same paragraph and do not create visible line breaks, so you can split long text across source lines for easier editing.

Example

Quisque egestas convallis ipsum, ut sollicitudin risus tincidunt a. Maecenas interdum malesuada egestas. Duis consectetur porta risus, sit amet vulputate urna facilisis ac. Phasellus semper dui non purus ultrices sodales.

Aliquam ante lorem, ornare a feugiat ac, finibus nec mauris. Vivamus ut tristique nisi. Sed vel leo vulputate, efficitur risus non, posuere mi. Nullam tincidunt bibendum rutrum. Proin commodo ornare sapien. Vivamus interdum diam sed sapien blandit, sit amet aliquam risus mattis. Nullam arcu turpis, mollis quis laoreet at, placerat id nibh. Suspendisse venenatis eros eros.

Quisque egestas convallis ipsum, ut sollicitudin risus tincidunt a.
Maecenas interdum malesuada egestas. Duis consectetur porta risus, sit amet
vulputate urna facilisis ac. Phasellus semper dui non purus ultrices sodales.

Aliquam ante lorem, ornare a feugiat ac, finibus nec mauris. Vivamus ut
tristique nisi. Sed vel leo vulputate, efficitur risus non, posuere mi. Nullam
tincidunt bibendum rutrum. Proin commodo ornare sapien. Vivamus interdum diam
sed sapien blandit, sit amet aliquam risus mattis. Nullam arcu turpis, mollis
quis laoreet at, placerat id nibh. Suspendisse venenatis eros eros.

End a line with two spaces or a backslash to request an explicit line break within the same paragraph. Unlike a blank line, this does not start a new paragraph.

Example: Explicit line break

First line Second line

A new paragraph with an explicit break.
Another line in the same paragraph.

First line
Second line

A new paragraph with an explicit break.\
Another line in the same paragraph.

Inline text formats

Inline formats can be embedded within any sentence or paragraph, and can also be combined. Use bold for emphasis, italics for a term or title, inline code for literal commands or field names, and strikethrough for text marked as removed. Surround just the words you want to format with the matching markers.

Example: Individual formats

bold text; italicized text; code; ~~strikethrough~~

**bold text**;
_italicized text_;
`code`;
~~strikethrough~~

Example: Formatting within a sentence

In our fieldwork, we record habitat conditions using the sample_id field. The ~~draft~~ final protocol includes important sampling guidance.

In our **fieldwork**, we record _habitat conditions_ using the `sample_id` field.
The ~~draft~~ final protocol includes **_important sampling guidance_**.

Combine bold and italic, or emphasise part of a sentence. Underscores are an alternative to asterisks.

Example: Combined emphasis

Bold and italic

Bold with an italic phrase inside.

Italic and bold using underscores.

**_Bold and italic_**

**Bold with an _italic phrase_ inside.**

_Italic_ and __bold__ using underscores.

You can also embed inline HTML tags in Markdown text: <mark> highlights text, <sub> creates subscript, and <sup> creates superscript. These are HTML tags, not Markdown markers; each needs a matching closing tag. More examples are on the HTML with Markdown page.

Example: Inline HTML

The sampling period is important. Water is H₂O, and we measure the study area in km².

The <mark>sampling period</mark> is important. Water is H<sub>2</sub>O, and
we measure the study area in km<sup>2</sup>.

Block quote

A block quote distinguishes quoted material from your own writing. Start each quoted line with >, and include a > on blank lines between quoted paragraphs. Add attribution when quoting another source.

Example

Once upon a midnight dreary, while I pondered, weak and weary,
Over many a quaint and curious volume of forgotten lore,
While I nodded, nearly napping, suddenly there came a tapping,
As of some one gently rapping, rapping at my chamber door.
“‘Tis some visitor,” I muttered, “tapping at my chamber door-
Only this, and nothing more.”

> Once upon a midnight dreary, while I pondered, weak and weary,\
> Over many a quaint and curious volume of forgotten lore,\
> While I nodded, nearly napping, suddenly there came a tapping,\
> As of some one gently rapping, rapping at my chamber door.\
> "'Tis some visitor," I muttered, "tapping at my chamber door-\
>  Only this, and nothing more."

Example: Quotation with a citation

Put the attribution in its own paragraph within the quote. Include the author and work title, plus publication details or a source link when needed. A block quote formats the quotation and citation; it does not generate references automatically.

Once upon a midnight dreary, while I pondered, weak and weary,
Over many a quaint and curious volume of forgotten lore,

— Edgar Allan Poe, The Raven.

> Once upon a midnight dreary, while I pondered, weak and weary,\
> Over many a quaint and curious volume of forgotten lore,
>
> — Edgar Allan Poe, _The Raven_.

Quotes can contain nested quotes, paragraphs, lists, and other Markdown. These ordinary quotes do not become layout blocks unless you add the classes described in the Markdown with layout classes guide.

Example: Nested quotations

A fieldwork observation.

A supporting observation from the team.

Record the location.

Explain the context.

> A fieldwork observation.
>
> > A supporting observation from the team.
>
> - Record the location.
> - Explain the context.

Fenced code block

A fenced code block displays code or literal text without interpreting its Markdown formatting. Place matching fences of at least three backticks or three tildes before and after the content.

An optional language name, such as json, enables syntax highlighting if an appropriate syntax-highlighting stylesheet is added and loaded by the site. Jekyll generates the syntax classes, but this theme does not currently include colours for them. See Jekyll’s guide to syntax-highlighting stylesheets and Rouge’s stylesheet-generation instructions for how to obtain the CSS. The stylesheet must then be included in the site’s styles or loaded by its layout.

Example

{
  "firstName": "John",
  "lastName": "Smith",
  "age": 25
}

```json
{
  "firstName": "John",
  "lastName": "Smith",
  "age": 25
}
```

Footnotes

Footnotes are automatically collected at the bottom of the page’s Markdown content, no matter where you write their definitions in the source. On this page, that is the bottom of the page. If a page also uses YAML content blocks, those blocks appear after the Markdown content and its footnotes. Click the superscript number to jump to the note; the selected note is highlighted, and its return arrow takes you back to the original sentence.

Footnote content can use Markdown, including bold, italic, links, inline code, lists, and multiple paragraphs. Indent continuation paragraphs and lists by four spaces to keep them in the footnote. The examples below show a simple note and a richer note with Markdown formatting.

Example: Simple and Markdown footnotes

This sentence has a simple footnote.¹

This sentence has a footnote containing Markdown.²

This sentence has a simple footnote.[^1]

This sentence has a footnote containing Markdown.[^methods-note]

[^1]: This is a simple, single-paragraph footnote.

[^methods-note]:
    Footnotes can include **bold**, _italic_, a [link to the Markdown guide](https://jcu-eresearch.github.io/jcu-research-website-theme/reference/plain-markdown/), and inline code such as `sample_id`.

    This second paragraph belongs to the same footnote.

    - Record the observation date.
    - Describe the sampling conditions.

Lists

Lists make related items easier to scan. Use an ordered list when sequence matters, an unordered list when it does not, or a task list to show completion status.

Ordered list

Start each item with a number, a full stop, and a space. You can use 1. for every source item; the rendered list numbers them in sequence. Indent nested items and continuation lines beneath their parent item.

Example

First item
- Indented bullet point
Second item
1. Indented numbered item with long text - Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
Third item

1. First item
   - Indented bullet point
1. Second item
   1. Indented numbered item with long text - Lorem ipsum dolor sit amet, consectetur adipiscing
      elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut
      enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut
      aliquip ex ea commodo consequat.
1. Third item

Unordered list

Start each item with a marker and a space. The markers -, *, and + all create bullets; the example below mixes markers at different nesting levels. Indent child items beneath their parent, and keep the same marker within each level of a continuous list. The theme displays the same solid marker at every level: a line by default, or a circle when theme_settings.bullet_style is set to circle.

Example

Top level item 1
- Indented once
  - Indented twice
Top level item 2

- Top level item 1
  * Indented once
    - Indented twice
- Top level item 2

Task list

Task lists show completed and incomplete items. Use - [x] for a checked item and - [ ] for an unchecked item. These checkboxes show the status written in the source; visitors cannot change them on the published website.

Example

Item 1
Item 2
Item 3

- [x] Item 1
- [ ] Item 2
- [ ] Item 3

Lists with paragraphs and code

Indent continuation paragraphs and code beneath the list item they belong to.

Example

Prepare the observations.

This paragraph belongs to the first item.
```
site,date,observation
```
Review the results.

1. Prepare the observations.

   This paragraph belongs to the first item.

   ```text
   site,date,observation
   ```

2. Review the results.

Horizontal rule

A horizontal rule creates a visual divider between sections. Put three hyphens on their own line, with blank lines before and after. Asterisks or underscores can also form a rule; keep the divider separate from text to avoid creating an underlined heading.

Example

---

Definition list

A definition list pairs a term with its explanation. Write the term on one line, followed by a line beginning with a colon and a space. This Kramdown extension is useful for glossaries and short descriptions.

Example

term 1: definition 1
term 2: definition 2

term 1
: definition 1

term 2
: definition 2

Longer definitions

Definition lists can have multiple terms or definitions and indented continuation paragraphs.

Example

Habitat
Study area: The environment in which observations are recorded.
Record its location and relevant characteristics.; An alternative definition can be supplied for the same terms.

Habitat
Study area
: The environment in which observations are recorded.

  Record its location and relevant characteristics.

: An alternative definition can be supplied for the same terms.

Link

A link connects readers to another page, website, or section. Put meaningful link text in square brackets and the destination in parentheses. Use a full URL for an external website or a relative path for a page within your site.

Example

View example.com

[View example.com](https://www.example.com)

Example: Link to a section on this page

Use # followed by a heading’s ID to link within the current page. Follow this link to the example heading, then use its return link to come back here.

Visit the Heading IDs example.

[Visit the Heading IDs example](#custom-id).

Example: Link to a section on another page

Add the section’s ID after the destination page path to jump directly to that section. This relative link opens the Theme purpose section on the homepage landing page, which has the explicit ID theme-overview.

Goto Theme purpose.

[Goto Theme purpose](https://jcu-eresearch.github.io/jcu-research-website-theme/#theme-overview).

Put a full URL inside angle brackets to create an automatic link whose label is the URL itself. Optional quoted titles are supported on links and images; make the visible label meaningful rather than relying on a hover tooltip.

Example: Alternate link format and link titles

https://www.jcu.edu.au/

James Cook University

<https://www.jcu.edu.au/>

[James Cook University](https://www.jcu.edu.au/ "University website")

Image

An image uses an exclamation mark, alternative text in square brackets, and the image path in parentheses. Describe the image’s relevant content in the alternative text. Relative paths are resolved from the page’s published address.

Example

Biscuit

![Biscuit](/jcu-research-website-starter/assets/sample-images/my-cat_750x750.jpg)

Linked image

Wrap an image in link syntax to make it a clickable destination. The inner syntax defines the image and its alternative text; the outer parentheses contain the link destination.

Example

[![Southern cassowary](/jcu-research-website-starter/assets/sample-images/card-cassowary.svg)](../../sample-content/content-blocks/southern-cassowary/)

Reference-style links and images

Define a destination once and reuse its label. Full, collapsed, and shortcut reference links are supported. Reference-style images use the same destination definitions. Definitions do not appear in the finished text. To make a reference-style image clickable, wrap it in a reference-style link: [![Alternative text][image-reference]][destination-reference].

Example

Visit JCU, university, or university.

Southern cassowary

[Visit JCU][university], [university][], or [university].

![Southern cassowary][cassowary-image]

[![View the southern cassowary profile][cassowary-image]][cassowary-profile]

[university]: https://www.jcu.edu.au/ "James Cook University"
[cassowary-image]: ../../assets/sample-images/card-cassowary.svg "Southern cassowary illustration"
[cassowary-profile]: ../content-blocks/southern-cassowary/ "Southern cassowary profile"

Table

Tables organise comparable information into rows and columns. Separate cells with pipes, and place a separator row beneath the header. Keep each row on one source line; alignment and inline formatting are demonstrated later on this page.

Example

Syntax	Description
Header	Title
Paragraph	Text

| Syntax    | Description |
| --------- | ----------- |
| Header    | Title       |
| Paragraph | Text        |

Colons in the separator row select left, centre, or right alignment. Cells can contain inline Markdown. Escape a pipe when it is part of cell text, and keep each table row on one source line.

Example: Alignment and cell formatting

Topic	Status	Count
Fieldwork	Complete	12
Analysis	In progress	4
Rainforest \| coast	Planned	2

| Topic               |   Status    | Count |
| :------------------ | :---------: | ----: |
| **Fieldwork**       |  Complete   |    12 |
| Analysis            | In progress |     4 |
| Rainforest \| coast |   Planned   |     2 |

Abbreviations

Kramdown abbreviation definitions attach an explanation to matching words. Do not rely on a hover explanation alone; spell out unfamiliar terms in the surrounding text.

Example

Environmental DNA (eDNA) can help identify species. Our eDNA samples are reviewed alongside field observations.

Environmental DNA (eDNA) can help identify species. Our eDNA samples are reviewed alongside field observations.

*[eDNA]: Environmental DNA

Escaping characters and HTML entities

A backslash makes a formatting character literal. HTML entities can represent symbols, reserved characters, and nonbreaking spaces.

Example

*These asterisks are visible*, as is # this hash.

Use <sample>, A & B, and 10 km.

\*These asterisks are visible\*, as is \# this hash.

Use &lt;sample&gt;, A &amp; B, and 10&nbsp;km.

Automatic contents lists

Attach {:toc} to a list to replace it with links to the document headings. This generates links within the page, not links to other pages. For a section overview, write an ordinary list of page links instead. Headings can be excluded using {:.no_toc} directly beneath them.

To exclude all headings below a chosen level, place {::options toc_levels="1..2" /} near the top of the page, before the contents list. This includes only H1 and H2 headings; use "1..3" to include H3 headings too. You can still use {:.no_toc} to exclude individual headings within the included levels.

This page uses H3 headings for both subsections and examples, so a heading-level limit cannot distinguish between them. Its Example headings use {:.no_toc} individually to keep the subsections in the contents list while excluding the examples.

Example

The generated list under Contents shows the output of this pattern.

- Contents
{:toc}

## A section

Section text.

## A heading to omit
{:.no_toc}

Example: Limit the heading levels

{::options toc_levels="1..2" /}

- Contents
{:toc}

## Included section

### Subsection omitted from the contents

Attribute lists and reusable attributes

Kramdown attributes can assign IDs or existing CSS classes to an element. An attribute alone does not create a new style. The theme-specific layouts are displayed on the Markdown-with-classes sample and how to use them is explained in Markdown with layout classes. Span attributes follow the text element; block attributes follow the block on a new line.

Example

This is important.

A paragraph with a custom ID.

This paragraph uses a reusable attribute definition.

This is _important_{: .sample-emphasis}.

A paragraph with a custom ID.
{: #sample-paragraph}
{:research-note: .jcu-alert .jcu-alert--warning}
This paragraph uses a reusable attribute definition.
{:research-note}

Separating adjacent blocks

The Kramdown end-of-block marker ^ separates constructs that would otherwise be combined. It is useful when two adjacent lists should remain separate.

Example

First list.

Second list.

- First list.

^

- Second list.

Parser comments and literal content

Kramdown comment extensions omit their contents. The nomarkdown extension passes content through without Markdown processing. These are advanced parser extensions; use ordinary code fences to show source code to readers.

Example

This source example illustrates a hidden comment and content passed through without Markdown processing.

{::comment}
An editing note that will not appear in the page.
{:/comment}
{::nomarkdown}

<p>Literal HTML output with **unprocessed Markdown markers**.</p>
{:/nomarkdown}

HTML alongside Markdown

Inline HTML can supply elements Markdown does not define, such as highlighting, subscript, superscript, or collapsible sections. See the HTML with Markdown sample for rendered examples and copyable source, and the HTML and Markdown guide for authoring instructions.

Features requiring additional support

The parser recognises mathematical markup, but this theme does not load a mathematics renderer; parsing it is not enough to display equations. Mermaid fences remain code unless a diagram renderer is added. GitHub-specific alerts such as [!NOTE], emoji shortcuts, mentions, and issue references are not enabled as GitHub features by this theme’s configuration. Use the theme’s alert blocks and actual Unicode emoji where appropriate.

This page covers the currently configured authoring features. Advanced Kramdown options can change parsing behaviour, and are not needed for normal content editing. Consult the Kramdown syntax reference and GFM parser documentation for detailed syntax rules. Changing the site’s parser or plugins can change what is supported.

This is a simple, single-paragraph footnote. ↩
Footnotes can include bold, italic, a link to the Markdown guide, and inline code such as sample_id.

This second paragraph belongs to the same footnote.
- Record the observation date.
- Describe the sampling conditions.
↩