Writing with Markdown

Pages are plain text in Markdown: a few marks, like * and #, that read well as text and turn into a web page. Each example below shows the Markdown, then what siv makes of it.

siv reads CommonMark, plus tables, footnotes, strikethrough, task lists, heading anchors and definition lists.

Paragraphs # ↑

A blank line starts a new paragraph. Lines next to each other join into one paragraph, so you can break lines wherever you like.

Write as you would write an email. This line joins the one above.

A blank line starts a new paragraph.

To break a line inside a paragraph, end it with a backslash:

Roses are red,\
violets are blue.

Bold, italic and code # ↑

*Italic*, **bold**, ~~strikethrough~~ and `code`.

Headings # ↑

A line starting with # is a heading. The page title is the biggest heading, so on a page start from ##:

## A heading

### A smaller heading

#### The smallest

The headings of this manual are made like this. Each heading gets an anchor, made of its text: "Bold, italic and code" gets #bold-italic-and-code. An anchor is the part of an address after #, so a link can open the page at that heading. Move the mouse over a heading to see its # link, and copy the address from it.

When a page has two or more headings, the starter shows a table of contents at the top, like the one on this page.

To choose the anchor yourself:

## Fix it now {#fix}

Links # ↑

Read the [siv home page](https://terokarvinen.com/siv). Back to the [contents](../). Up to [Paragraphs](#paragraphs) on this page.

Link to your own pages with a path from this page: ../other-page/. Or from the site's root: /other-page/. siv checks every link to your own pages when it builds, and a broken one stops the build.

Bare addresses become links by themselves:

See https://example.com/ or www.example.com, or write to tero@example.com.

Lists # ↑

- Lists start with a dash
- Each item on its own line
    - Indent four spaces for an inner list
- Back to the outer list

1. Numbered lists
2. Work the same way

A task list has a box in each item:

- [x] Buy coffee
- [ ] Write the article

A definition list explains words:

Static website : A website made of plain files, without code running on the server.

Code # ↑

Indent with a tab # ↑

The quickest way to show code is to indent it with a tab, or four spaces. siv guesses the language and colors it. Lines starting with $ are commands; the rest is their output:

List the files:

	$ ls -a
	.  ..  content  siv.toml  templates

$ ls -a
.  ..  content  siv.toml  templates

The same works for code in many languages:

	def hello(name):
	    print(f"Hello, {name}")

def hello(name):
    print(f"Hello, {name}")

siv guesses from clear signs only: a first line starting with $ , a #! line, and the typical marks of C, HTML, CSS, Python, shell and JavaScript. When it's not sure, the code stays plain text, without colors:

	Tugboat   1970
	Ferry     1956

Tugboat   1970
Ferry     1956

Name the language # ↑

For a longer example, or to name the language yourself, put the code between lines of three backticks, with the language after the first ones:

```c
#include <stdio.h>

int main(void) {
    printf("Hello\n");
    return 0;
}
```

#include <stdio.h>

int main(void) {
    printf("Hello\n");
    return 0;
}

Known names: python, bash, sh, c, go, rust, java, js, html, css and many more. text turns the colors off. linuxcli (or console) colors $ lines as commands and the rest as output, even when the first line isn't a command:

```linuxcli
Install the web server:
$ sudo apt-get install apache2
Reading package lists... Done
```

Install the web server:
$ sudo apt-get install apache2
Reading package lists... Done

When you copy commands from the page, the $ isn't copied along.

Code in a sentence # ↑

Backticks inside a line make code in a sentence: `siv build` shows as siv build.

Turn guessing off # ↑

Guessing is on by default. To turn it off for the whole site:

$ siv config autodetect-code-lang false

Or for one page, in its front matter: autodetect-code-lang = false.

Quotes # ↑

> A quote starts with a greater-than sign.
> Quotes stay "as you typed them".

siv leaves quotation marks as you typed them: curly quotes differ between languages.

Tables # ↑

| Boat    | Year |
|---------|-----:|
| Tugboat | 1970 |
| Ferry   | 1956 |

The colon in -----: aligns a column to the right. The columns don't need to line up in the text.

A table copied from a spreadsheet is tab-separated. Put it in a ```tsv block as it is:

```tsv
Boat	Engine	Power
Tugboat	1.2	62
Canoe	0.9	27
```

Columns of numbers are aligned to the right by themselves. A tsv block can also become a chart: Charts.

Footnotes # ↑

siv is one file.[^single]

[^single]: A static binary, without dependencies.

The footnotes are collected at the end of the page, with links back.

Images # ↑

An image alone on its line becomes a figure, with its description as the caption:

![Sunrise over a lake](lake.jpg)

Put the image in the page's folder. siv makes every size a screen needs. More in Images.

The summary # ↑

The front page and other lists show each page's first paragraph as its summary. To choose a longer summary, put a <!--more--> line after it:

The first paragraph.

The second paragraph, also in the summary.

<!--more-->

The rest of the page.

Notes to yourself # ↑

HTML comments are not published:

Visible text.

<!-- Check the version numbers before the next course. -->

Other HTML is published as it is, for the rare thing Markdown can't do: HTML.

Next: Images