Introduction

Working on the UCC web site has never been simpler. You can take a copy of the site using git, run it locally on your own Linux or Windows desktop and then push the changes back into the main repository to have them automatically deployed live by continuous integration.

If you're worried about breaking something, or aren't in the webmasters group, you can also make a pull request to have someone review your changes before they go live.

Before you start you'll need:

• A copy of git, which you can install using the following guide, and,
• Python 3.7 or later, available on the Python site.
• An account on https://gitlab.ucc.asn.au/. If you have trouble signing up, shout out in #ucc on Discord.

Cloning and Running the Site

To get started:

• Clone the UCC Website repository:

  git clone [email protected]:UCC/ucc-website.git
  

• Run kondo/server.py:

  cd ucc-website
  python3 kondo/server.py -r
  

  On Windows, Python 3 may be installed as py rather than python3.

  The -r argument enables hot reloading, so you don't have to refresh pages after making changes.

• All going well, the following should be printed:

  Development server running on port 8000.
  

• Navigate to http://127.0.0.1:8000/kondo/index.ucc, which should be this document.

Writing a Page

Web pages are simply Markdown files with the extension .ucc.

To write a new web page, create a Markdown file with the extension .ucc^[1]:

# Hello, world!

This is a new document!

If you've used Markdown previously (such as on GitHub) the syntax should be quite familiar^[2]. If not, all the styles that are available are documented later in this introduction.

Finding an Existing Page

A page address that ends in .ucc is easy enough to find; for example, /tools/lart.ucc would be found in:

• ucc-website/tools/lart.ucc.

However, without the .ucc extension, such as for the path /tools/cupboard, the file could be in:

• ucc-website/cupboard/index.ucc,
• ucc-website/cupboard/index.md,
• ucc-website/cupboard.ucc, or,
• ucc-website/cupboard.md.

Headings and Paragraphs

Paragraphs in Markdown are blocks of text separated by blank lines:

This is a paragraph.
Even though it has two lines.

This is a second paragraph.

They can be word-wrapped manually—that is, they can be multiple lines—but setting up your editor for visual word wrapping and placing the entire paragraph on a single line is generally easier.

There are multiple levels of heading, which should be used to establish a hierarchy rather than to pick the font size^[3].

# Top Level Heading
## Second Level Heading
### Third Level Heading

Italics, Bold and Keywords

Markdown supports the following ways of adding emphasis to spans of text:

This is *in italics*.

This is in **bold**.

This is an ``inline code block``.

This is ~~struck out~~.

Inline code, paths, and keywords and identifiers are best placed in inline code blocks, which uses a specific font and makes it clear that the contained text is more than just an English word or phrase.

Inline code blocks also make normally special characters visible:

This text ``won't be *bold*``.

Links and Images

A link can be a relative path, relative to the current document, an absolute path with a leading /, or a web address of a different site:

Read about [plugins](plugins.ucc).

Back to the [contents](../).

Are you [thirsty](/services/drink.ucc)?

A [cool site](https://mrgris.com/projects/oilslick/).

Images are the same as links, but with a ! placed before them:

![UWA Crest](/kondo/images/uwa-crest.svg)

The description part ("UWA Crest") is placed in the alt tag.

Lists

There are bullet point lists:

- First item.
- Second item.
    - Detail one.
    - Detail two.

And numbered lists:

1. Collect underpants.
2. ?
3. Profit.

A list item can be multiple paragraphs:

- First line.
- Second line.

  With a second paragraph.
  
  And a third.

Quotations

Text can be put into a quotation block:

> Nel mezzo del cammin di nostra vita
> mi ritrovai per una selva oscura,
> ché la diritta via era smarrita.

This tends to have been used on old pages as a way to highlight text blocks, rather than as actual quotations.

Code Blocks

Code and command lines—or other text that should be rendered with a monospaced font—can be placed in code blocks:

```
 /\_/\
( o.o )
 > ^ <
```

Tables

Markdown tables are supported, including support for setting column alignment:

| Name  | Age  | Colour |
| ---   | ---: | ------ | 
| Sam   | 2    | Tabby  |
| Henry | 3    | Black  | 

Titles

The first Markdown heading you use in a document is, by default, also used as the title of the web page, which is visible:

• In the title bar of a desktop browser, and,
• When a bookmark of the page is made.

As an example, if the first Markdown title was:

# My Document

Then the title (<title>) of the page would default to "My Document".

To override this default, in the first line of the .ucc page, place the following:

@title My Great Document

# My Document

The @title line is a directive, which is a feature specific to the UCC. Directives are described further in the Extensions section.