Markdown Basics

Everything on mishmash.no is written in Markdown. This page covers the whole of what you need. It is short, because Markdown is small.

The idea

Markdown lets you write formatted text with ordinary characters. You type ## Introduction and get a heading. You type [our website](https://mishmash.no) and get a link.

You never touch HTML, and you never fight with a toolbar.

The cheat sheet

To get	Write	Result
A heading	## About the centre	A section heading
A smaller heading	### Funding	A subheading
Italic	*emphasis*	emphasis
Bold	**strong**	Sparingly. House style is plain prose
A link	[MishMash](https://mishmash.no)	MishMash
A bullet list	- first on its own line	A bulleted list
A numbered list	1. first on its own line	A numbered list
An image		See Adding Images
A quotation	> quoted text	An indented quote
Code or a filename	`site/index.md`	site/index.md

Three rules that catch most people out:

Start headings at ##, not #. The page title comes from the frontmatter, and a single # produces a second, competing title.

Leave a blank line between paragraphs. One newline is not enough; Markdown will run the lines together.

Leave a blank line before a list. Without it the list gets absorbed into the paragraph above.

House style

Three conventions on this site, all visible if you read a few existing pages:

Write plain prose. Avoid bold in the middle of sentences; if a point needs emphasis, structure the sentence so it lands on its own. Backticks for filenames and literal on-screen labels are fine and encouraged.

Write for a reader who is not in your field. This is a centre spanning music, informatics, media studies, law and library science, and the site is read by the public.

No dashes with spaces around them. A sentence broken by — is the clearest sign that a paragraph came out of a language model, and the site is written by people. Use a comma, a colon or a full stop, and where you want a dash pair, a pair of commas does the same job:

Instead of	Write
Yes — the site is a playground	Yes. The site is a playground
three levels — Simple, Standard and Advanced — and you choose	three levels, Simple, Standard and Advanced, and you choose
- [Glossary](/about/glossary/) — key terms	- [Glossary](/about/glossary/): key terms

An en dash with no spaces is correct where it joins two things, and stays: 13–14 April, nob–nno. So is any dash inside somebody else's words, such as the title of a talk, a partner's own name or a speaker's abstract. scripts/check_dashes.py runs on every push and reports the rest; it lists the accepted exceptions with the reason for each.

Frontmatter

Every page file starts with a block fenced by three dashes:

---
layout: page
title: "Frequently Asked Questions"
description: "Common questions about MishMash."
---

This is frontmatter. It is settings rather than content: it does not appear on the page as text, but it controls the page. The format is YAML.

Common fields:

Field	What it does
title	The page heading, the browser tab, and the search result
layout	Which template renders the page: page, default, event, person
description	One-sentence summary, used in listings, search, and link previews
date	Publication date, required for news and events
permalink	Forces a specific web address
image	Thumbnail shown in listings and when the page is shared
lang: nb	Marks the page as Norwegian
translation_url	Links this page to its counterpart in the other language

Which fields a page needs depends on what kind of page it is. Adding News and Adding Events give the exact list for each.

Rules for the frontmatter block:

• It must be the very first thing in the file. No blank line above the opening ---.
• Both --- lines are required.
• Indentation is significant, and it must be spaces, never tabs.
• Wrap a value in double quotes if it contains a colon, otherwise YAML reads the colon as a new setting. title: "MeshUp: AI and dance" is fine; without the quotes it breaks.

If a page fails to build, mistyped frontmatter is the most likely cause. See When Things Go Wrong.

Things that are not Markdown

Reading existing pages you will meet lines in curly braces:

{% include events_wp_pages.html wp="WP1" %}

That is Liquid, the template language Jekyll uses. It pulls in a shared component, here the list of events belonging to work package 1. Leave these alone unless you know what they do; deleting one silently removes a section of the page.

You will also occasionally see raw HTML, which Markdown allows. The FAQ page uses it for expanding sections. Copy the pattern from a neighbouring entry if you need to add one.

Checking your work

In the GitHub web editor, the Preview tab shows the formatting. It renders GitHub's own flavour of Markdown rather than the site's exactly, so it is a good check for structure and a rough one for appearance.

To see the page exactly as it will appear, you need the site running on your own machine. That is Running the Site Locally, and it is worth doing once you edit regularly.

Next

• Adding News: a news post from a template
• Adding Events: an event with dates and a calendar entry
• Adding Images: where pictures go and how to reference them