User's guide

20 November 2024

This guide provides a quick introduction to using this site, configuration and formatting articles (with markdown).

Using PPost

When writing a new post it goes to drafts. From here, viewing the post, it can be edited, published (made viewable to those not logged in) and deleted.

Customising PPost

This site can be configured using a special post in drafts named -site-settings-.

The config format is a header line followed by some content. The possible config headers are:

[title]

The site’s title. This option accepts valid markdown.
[description]

The description of the site that sits between the site title and the list of articles. This option accepts valid markdown.
```
[title]
Trains of London


[description]
A blog where I discuss my favourite **trains** in and around London.
> this is a good blog
```
[custom-css]

Custom CSS modifications to append to the existing stylesheet.

For example add the following to remove the login nav link
```
[custom-css]
#nav-login {display:none}
```
[nav]

A navigation bar to customise. This option accepts valid markdown.

The recommended method of configuring this is with a list of links:
```
[nav]
<li> [my post](/p/path-to-post)
<li> [see this](https://example.com)
```

Keyboard Shortcuts

There are number of accesskey-based shortcuts where a couple keys are pressed before a single letter to trigger a link (on Macs the keys are Control + Option),

Everywhere

h - go to the home page
t - go to the tags page
l - go to the login page

Logged In

d - go to the drafts page
n - go to create a new post

On a Post

e - edit the post
p - publish the post
x - delete the post
s - submit the post

Exports

Navigate to /export or click the button on the drafts page to download a backup of the database.

Then use something like the following to dump the $DB_FILE to markdown files.

for item in $(sqlite-utils $DB_FILE "select slug, displaytitle, markdown from posts"); do
    file="$(jq .slug <<< "$item").md"
    printf "# $(jq .displaytitle <<< "$item")" > "$file"
    printf "$(jq .markdown <<< "$item")" >> "$file"
done

Markdown Guide

The content on this site is written in markdown - even this page (click “edit” next to this page’s title to see its markdown contents). Markdown is a format for writing structured documents.

Standard HTML can always be used here for more control than markdown gives.

Here is a quick run through of some ways you might use it:

Formatting:

_italics for emphasis_

italics for emphasis

**embolden this text**

embolden this text

# Heading 1
## Heading 2
### Heading 3

>You can quote me on this

You can quote me on this

```
A code block is marked by a fence of backticks
and can be coded "inline" using `single backticks` <-
```

Bullets:

* Any
* Old
* Order

Any
Old
Order

1. Numbered
1. Auto-
1. Magically

Any
Old
Order

Links and Images:

[the link words](https://wikipedia.org)

the link words

![describe the image](https://commonmark.org/help/images/favicon.png)