Writing work can be tricky at times, and Quilt doesn’t have a large group of professional writers on hand for advice. This document is intended to be a set of guidelines, tips, and tricks to use when writing documents, articles, blog posts, and other written content for the site.

Editors & Setup

Using Visual Studio Code or VSCodium is recommended. When opening the site with VSCode, you should see a popup in the bottom right asking if you want to install some recommended extensions. If you don’t see it, you can also type @recommended into the extensions searchbar:

Spelling, Punctuation & Grammar

This goes without saying, but proper spelling and grammar is fairly important. That said, nobody is perfect and there are tools out there that make everyone’s lives easier. The use of one is highly recommended, even if you usually have excellent spelling and grammar — everyone makes mistakes!

• LanguageTool remains one of the best tools available for this, even the free version. VSCode with the LTeX extension — or IntelliJ IDEA — is an easy way to use LanguageTool.
• Grammarly exists as an alternative, but LanguageTool’s open-source approach tends to result in a more trustable tool.

A somewhat formal tone in your writing is also recommended, but there’s absolutely no need to completely avoid an informal approach. The site even supports emojis (Meta + .), if that’s something you’re into. 🥔

It’s also worth thinking a little about punctuation — you can use - for a hyphen, with -- and --- existing for progressively longer dashes. If you’re looking to join to words together (like-this), use a single hyphen. To break apart a sentence — like this — use two dashes.

Front Matter

A front matter block must be placed at the top of every document or page that’s written for the site. It takes the form of a block of YAML surrounded by triple dashes (---), and should contain at least a title and layout property.

---
title: This is the title of the page or blog post.
layout: /src/layouts/Page.astro
---

Pages that don’t contain a layout property in the front matter will be output as plain HTML (no sidebar, no styling, nothing). Below are some front matter properties:

• layout — Layouts are in the /src/pages directory. Most of the pages either use /src/layouts/Page.astro (for pages, such as About, Community, etc.) and /src/layouts/Post.astro (for blog posts). The Install section of the site uses a different set of layouts (/src/layouts/Install.astro for the main page and /src/layouts/InstallPage.astro for the launcher pages).

• draft — If you’re working on something that needs to be committed but not visible to the public on the site, you can set this to true.

More information on this can be found in the Astro documentation.

Author Information

Author information can be specified using the authors property in the front matter:

---
authors:
  - person-one
  - person-two
---

Components

To use any components that require importing, you’ll need to be in a .mdx file instead of a .md file. There’s no difference between the Markdown in these two filetypes, so you can just rename any existing Markdown file.

Messages

Message — this allows you to create a Message, as shown below. Messages are essentially boxes that draw attention to a specific block of text.

import Message from "@atoms/Message.astro";

<Message style="success">
	This message has no title, but it has the "success" styling.
</Message>

<Message title="Title goes here" style="danger">
	This message has a title, and the "danger" styling.
</Message>

Columns

Columns aren’t particularly complex. Columns on this site will collapse nicely for mobile users, with the leftmost column showing first. Here’s an example to show how to use them:

Example

<div class="columns">
	<div class="column">
		<Message>
			This is column 1.
		</Message>
	</div>
	<div class="column">
		<Message>
			This is column 2.
		</Message>
	</div>
</div>

Result

Articles, Documents and Pages

When working on non-blog content, it’s worth keeping the following points in mind.

Front Matter (Pages)

For non-blog content, the following front matter properties may be useful:

• description — This is the page’s meta description that will be shown in search engines and on social media. If you skip this, then the site’s default description will be used instead.

Blog Posts

As writing blog posts is somewhat different from writing an article or document, you’ll need to do the following things in addition to the requirements for any other type of page:

• Include a date in the post’s front matter.
• Include author information in the post’s front matter, as detailed above.
• Define an excerpt in your post

For more information on these concepts, please see the following sections.

Front Matter (Blog)

For blog posts, you need to include a date field in the front matter, which should be in a standard ISO format (For example, 2022-05-07 4:30:00 -00:00). This is required for all blog posts, as the site relies on it for post ordering and to display metadata.

Excerpts

Excerpts are meant to be a summary of what’s in a blog post. Every blog post must have an excerpt — failing to provide one will make the entire post be used as the excerpt, which is definitely not what you want.

Typically, excerpts are generated from the first couple of paragraphs in a post. Using the special HTML comment <!-- MORE --> will mark all content above it as the excerpt.

One approach would be to write a summary at the top of an article, mark it as the excerpt and add a horizontal rule to split it from the rest of the page content:

A summary of the post goes here.

<!-- MORE -->

---

The actual post content starts here.

There are many ways to approach this, of course — it’s best left to the creative liberty of whoever’s writing the post, so this is just a suggestion.