Writing docs and posts

How the pages in Docs and Blog are made, for anyone editing this site. The site's source is public on GitHub (another site). This page also shows every piece of formatting the docs and blog support, so you can see how each one looks.

#Where files go

Every page is a markdown file. The file name is the address.

Names are lowercase with hyphens. A file whose name starts with _ is not built.

#Frontmatter

Each file starts with a few key: value lines between --- fences.

---
title: Installing YUKI
summary: One line for the index
group: yuki
order: 2
---

• title is required.
• summary shows under the title on index pages.
• date (posts, YYYY-MM-DD) sets the order on the blog. Undated posts are listed as drafts. Never make a date up.
• group (docs) is one of yuki, dex-place, or the retired dexcode and dexclient.
• placeholder: true marks a page that is still a stand-in. A doc shows the Placeholder tag and is hidden from search engines. A post is not published at all: no page, no place on the blog or in the feed, until the line goes. Leave it out, or set placeholder: false, on a finished page.

#Groups and order

Docs are listed by group, then by order, then by title.

#Formatting

Headings from ## down get a link and appear under On this page. Links to other sites, like the Ko-fi page (another site), are marked for screen readers. Keys look like Ctrl + C.

Code blocks name their language and get a copy button:

$ npm run dev
$ npm run build

1. Write the file.
2. Run npm run dev and open the page.
3. Commit when it reads right.

A plain quote:

Short text either helps someone use something or gives a real character a small voice.