“Programs must be written for people to read, and only incidentally for machines to execute.” Harold Abelson, Structure and Interpretation of Computer Programs

Just like source code, the markdown content you write in your .md files will be transformed into HTML as part of the Jekyll build process. However, it’s still a good idea to keep a consistent style across the markdown content that you write.

This style guide will guide you towards some best practices (in no particular order) in laying out your Jekyll site.

Use #s for headings#

You can use differing amounts of #’s to create headings in your Markdown document. The lower the amount of #’s the “bigger” the heading is.

For each Markdown file, the top-level heading is actually determined by your page title: key (in the YAML frontmatter block at the top of the page). In your content, you should start with level 2 headings ## for main headings, ### for sub-headings, etc. If you’re familiar with HTML, the number of #’s maps directly onto the heading level, e.g.

### My Heading

will be transformed into

<h3>My Heading</h3>

Being consistent and following the best practice here is good, especially because it makes the experience of browsing the site with a screen reader better.

## RGB

...

### A history

...

### Alternate color models

...

There’s nothing technically stopping you using level 1 headings (e.g. #) in your content. However, each page already has a level 1 heading from the page.title, an so if you add another one then you’re creating a confusing page structure, which is an accessibility problem s.

If you’re linking between pages on your site, you might be tempted to figure out the target link and provide it like so:

Remember, [Assignment 2](https://comp.anu.edu.au/courses/compXXXX/deliverables/ass2/) is due on Friday!

However, when the link is an internal link to another part of your Jekyll site (as is the case for the Assignment 2 example above) there’s a better way: use the link tag.


Remember, [Assignment 2]({% link _deliverables/ass2.md %}) is due on Friday!

This has a few benefits:

  1. Jekyll enforces that the link exists exists at build time—if it doesn’t, your site will fail to build (which is better than getting a panicked email from a student saying that there’s a broken link on the course website)

  2. when you’re previewing locally using bundle exec jekyll serve, the link will point to the local preview of the target file (i.e. https://127.0.0.1:4000/deliverables/ass2/ in the example above) rather than the real Assignment 2 page (which won’t have any local changes yet)

  3. if you end up moving your final site to another URL, you can just change the baseurl key in the master _config.yml, re-build your site, and all your internal links will point to the new locations

Linking to specific headings#

You can link to specific headings on pages by giving them an “anchor”, which you can append to the URL of a link.

This feature is not supported by standard Markdown, but instead by Kramdown–the specific implementation version of Markdown which Jekyll uses.

If you have a page page.md that has the content:

## Here's the heading you want to link to {#important-heading}

You can link directly to the heading by appending “#important-heading” to the URL, like so:


[see this important heading]({% link page.md %}#important-heading)

It’s important to note that Jekyll linking to a heading which doesn’t exist in this manner won’t cause any errors (like what would happen if you made a mistake with the link tag). To catch this sort of error you would need to enable html-proofer

Use code blocks#

Markdown provides two different ways of including source code in amongst the text of the document: inline, or as a “fenced” block.

If you’re referring to a small amount of code: a variable, function, or short code snippet, you can use an inline code block by surrounding it with backticks (`) like so `let x = resultFromFunction();`.

For larger snippets, you can “fence” the code block by surrounding it before and after with three backticks (`):

```
function add(a, b) {
  return a + b;
}
```

One other tip: highlight.js, the built-in syntax highlighter, will try and guess the language you’re using in your code block. However, you can be explicit (assuming the language is supported) by adding the language name to the opening backtick fence:

```javascript
function add(a, b) {
  return a + b;
}
```

Often you’ll either want to link to the same place, use the same image, or want to be able to change a link easily. For these cases you can replace the end of a Markdown link (the (...) bit with the URL in it), with a pair of square brackets with a label in it. This label can be a number, or some text.

<!-- we use the label "goog" for the URL of our links -->

[somewhere I link to often][goog]

...

[for when you need help][goog]

<!-- and here you define it to go to Google! -->

[goog]: https://google.com

This is a living document, and we will add to it over time. If you’ve got a particular suggestion, contact the CECS Jekyll web support team and they can add it to the guide.

arrow-left bars search times