Introduction#

Welcome! You’re in the right place if you want to:

  • update a page to correct some incorrect/out-of-date information
  • creating a new news/event page to tell the world about the cool stuff we’re doing

If you want to create a new website, start with the getting started for site developers page.

The good news is that you can do all of those things through the GitLab web interface.

Gitlab web interface#

You’ll be editing the website using the Gitlab web interface. You’ll need access to the relevant website “project” on GitLab—get in touch with CECS Jekyll web support if you need to be given access.

Please refer to the full guide for how to find the page you want to edit or create a new page.

Full guide: Content authoring via the web

Pages & Collections#

Each markdown (.md) file (we’ll talk about this file format soon!) you can see in the Gitlab web interface is a page in the website.

Pages are grouped into folders, and these groupings are called collections. Each top-level menu item usually corresponds to a collection.

For example you might have a “people” collection. In the Gitlab web interface, this is represented by the _people folder. Each file in that folder is a markdown page that represents a person—as you can see in the following screenshot (from the School of Cybernetics website, but the same principle applies for other websites with a People collection):

Web interface view for md files in the People collection

News & event pages are in the posts collection#

A notable exception to this pattern is news and events pages, which are located in the _posts folder. The “posts” collection contains all pages that have a date associated with them.

These files should be named in the format YYYY-MM-DD-short-title (separated using hyphens.) The date info is extracted from the file name.

Page options#

Each page has options you can set in a block at the top of the file (between the --- lines) called the front matter.

You set a page option by writing the name of the option on the left, followed by a colon (:) and then the value on the right.

Syntax#

Standard options#

Most pages have the following standard options you can set:

---
title: This is the title of the page
tagline: An optional tagline that's shown under the title
image: /assets/images/path-to-image.jpg
image_alt: An optional caption for the image, if unset title will be used
---

Collection-specific options#

Some collections are special cases, and pages in the collection have their own specific page options.

For example, people pages have lots of people-specific options or refer to the full guide for these special collections:

---
name: Ben Swift
position: Senior Lecturer
location: HN 2.36
image: /assets/images/people/ben-swift.jpg
email: ben.swift@anu.edu.au
phone: 6125-7027
web: https://benswift.me
google_scholar: OQdYgLEAAAAJ
twitter: benswift
linkedin: benjswift
tags:
  - computing-foundations
---

If you’re not sure what options are allowed - have a look at some other pages in the same collection.

Setting page tags#

Tags are useful to set on people or news / events (posts) pages. However, they look a bit different to normal options because you can set more than one tag.

List each tag on a new indented line, using a dash (-) as a list marker.

For example, to set tags on a post:

---
title: How to train your speech recognition model?
tags:
  - news
  - 3ai-masters
---

The tags will usually be all lowercase, with words separated by hyphens (-).

Page layouts#

All pages also have a layout option. A page’s layout determine’s how parts of the page are shown.

There are three layout options:

  • default - the default layout used for most pages
  • feature - for “feature” pages e.g. home page, landing page
  • person-detail - a special layout for pages in the “people” collection

If the layout page option is not set, the page will usually use the default layout, or the option that has been configured in the site settings (e.g. for the “people” collection.)

Default layout#

The default layout is, well, the default used on most pages.

Here’s a page that uses the default layout.

TODO: screenshot

The page has the following parts:

  • header - shows the title, tagline and image set in page options
  • table of contents - shows an auto-generated table of contents for the page content
  • page content - the content you write in each file under the page options
  • collection navigation - shows auto-generated links to other pages in the collection
  • related pages - shows a cards that link to related pages at the bottom of the page

Pages that use the default layout also have extra options that hide and show different parts of the layout. See the layout-specific options section below.

Feature layout#

The feature layout is for “feature” pages such as the home page or a landing page.

Here’s a page that uses the default layout.

TODO: screenshot

The page has the following parts:

  • image - full width banner with a background image, shows the title and tagline set in page options
  • page sections - the content you write under is split into multiple sections. Each level 1 or level 2 heading or page break will create a new section.

Please refer to the full feature layout guide for more detail on how the feature layout creates pages sections.

Full guide: TODO create page on how sectionify works

Pages that use the feature layout also have extra options that hide and show different parts of the layout. See the layout-specific options section below.

Person detail layout#

TODO: explain this layout

Page content#

About Markdown#

We’ve seen that the files that get turned into pages on the websites are in markdown format (.md). The content you write and edit will also be in Markdown syntax. This is basically like writing in a normal document, but there are shortcuts for creating things like headings, links, and images.

Markdown cheat sheet#

This Markdown cheat sheet provides a quick overview of basic Markdown syntax. It can’t cover everything so if you need more detail please refer to the full Markdown guide

Element Markdown Syntax
Heading 
## H2
### H3
#### H4
Bold 
**bold text**
Italic 
*italicized text*
Blockquote 
> blockquote
Ordered list 
1. First item
2. Second item
3. Third item
Unordered list 
- First item
- Second item
- Third item
Code 
`code`
Horizontal rule 
-----
Link 
[link text](https://www.anu.edu.au/)
Image 
![image alt text](/assets/images/example.png)

Using classes in Markdown#

Basic Markdown syntax lets us do things like create headings, links, and images. What if we wanted to create a link that looks like a button?

The website theme provides some useful classes for common elements.

Syntax#

In order to add a class to your markdown content, type curly braces ({}), and inside them type a colon (:) followed by a dot (.) and then the name of the class:

{: .class-name}

Please refer to specific examples below for how to apply the class.

Adding a lead paragraph#

Place {: .lead} after a paragraph to turn it into a “lead” paragraph. Eg:

Our community has built our identity. As early as our inception, our founders
agreed in order to create a genuine university community we needed more than
bricks and mortar.
{:.lead}

Our community has built our identity. As early as our inception, our founders agreed in order to create a genuine university community we needed more than bricks and mortar.

Adding a button#

  • Place {: .button} after a link to turn it into a black button. Eg:
[Click me](#adding-a-button){: .button}

Click me

  • Place {: .button--outline} after a link to turn it into an outline button. Eg:
[Click me](#adding-a-button){: .button--outline}

Click me

Adding a callout box#

  • Place {: .info-box} after a paragraph to turn it into a blue callout box. Use this box to call out extra informational content. Eg:
Please email the course co-ordinator if you have any questions.
{:.info-box}

Please email the course co-ordinator if you have any questions.

  • Place {: .warn-box} after a paragraph to turn it into a gold callout box. Use this box to callout important information or warnings. Eg:
This page is currently under maintenance. Sorry for any inconvenience.
{:.warn-box}

This page is currently under maintenance. Sorry for any inconvenience.

  • Place {: .error-box} after a paragraph to turn it into a red callout box. Use this box to call out critical information. Eg:
If this is an emergency, please stop reading and call 000 immediately.
{:.error-box}

If this is an emergency, please stop reading and call 000 immediately.

Including components#

For even more advanced content such as icons, the website theme provides some useful components which you can include in your content.

Syntax#

In order to include a component, you type things surrounded by curly brace percentage signs ({% %}). This syntax is from the Liquid templating language which our website theme uses.

If you’re interested in learning more about how this works, have a look at Jekyll documentation for includes.

Adding icons#

TODO: write a guide for this

Adding images with captions#

TODO: this component hasn’t been created yet

Adding videos#

The theme supports embedded YouTube videos, you just need to get the video ID and then include the following (replacing NiLJxA7DNog with your video ID):

{% include youtube.html id="NiLJxA7DNog" %}

Advanced topics#

Layout-specific page options: hiding parts of the page#

These are options that affect whether to show or hide elements that are specified by the default layout.

The default setting for all of these options is false, so you can set them to true on individual pages to tweak the default layout or site settings.

---
no_breadcrumb: false
no_title: false
no_image: false
show_collection: false
show_pagination: false
show_related: false
show_toc: false
---

The following also affect the feature layout:

---
no_breadcrumb: false
no_title: false
---

Using HTML in markdown#

Callout boxes with headings#

Adding grid columns#

Styling forms#

Liquid & Jekyll features#

There is also the ‘Using Liquid: programming pages’ page for extra information on Liquid.

Linking to internal pages: relative_url filter#

Including cards#

arrow-left bars magnifying-glass xmark