From 0ae9af323ffda2a7219df3a1493238807d2bddd5 Mon Sep 17 00:00:00 2001 From: Southpaw Date: Sun, 1 Sep 2024 19:30:27 +0100 Subject: [PATCH] Delete writing.mdx (most people can already write...?) --- src/pages/en/staff/outreach/writing.mdx | 206 ------------------------ 1 file changed, 206 deletions(-) delete mode 100644 src/pages/en/staff/outreach/writing.mdx diff --git a/src/pages/en/staff/outreach/writing.mdx b/src/pages/en/staff/outreach/writing.mdx deleted file mode 100644 index f8a05e39..00000000 --- a/src/pages/en/staff/outreach/writing.mdx +++ /dev/null @@ -1,206 +0,0 @@ ---- -title: Writing Guidelines -description: Tips and best-practices for writing content on the site. -authors: - - gdude2002 - - pluie - - "[object Object]" -layout: /src/layouts/StaffDocument.astro ---- - -import Message from "@atoms/Message.astro"; - -import TabBar from "@atoms/tabs/TabBar.astro"; -import TabBarLink from "@atoms/tabs/TabBarLink.astro"; -import TabContent from "@atoms/tabs/TabContent.astro"; -import TabGroup from "@atoms/tabs/TabGroup.astro"; - - - -**This document has completely changed.** As we have migrated from Jekyll to [Astro](https://astro.build), writing documents is now a vastly different process. Please contact [pluie](https://github.com/pluiedev) (`pluie#9105`) or [[object Object]](https://github.com/obj-obj) (`[object Object]#7105`) if you need any help writing new articles and these new guidelines aren't enough. Thanks for your patience! - - - -{/* - - - - - - - - First tab content - - - - Second tab content - - -*/} - -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](https://code.visualstudio.com) or [VSCodium](https://vscodium.com) 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](https://languagetool.org) remains one of the best tools available for this, even the free version. VSCode with [the LTeX extension](https://marketplace.visualstudio.com/items?itemName=valentjn.vscode-ltex) -- or IntelliJ IDEA -- is an easy way to use LanguageTool. -- [Grammarly](https://www.grammarly.com) 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. - -```yaml ---- -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](https://docs.astro.build/en/guides/markdown-content). - -### Author Information - -Author information can be specified using the `authors` property in the front matter: - -```yaml ---- -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. - -
-
- ##### Example - - ```astro - import Message from "@atoms/Message.astro"; - - - This message has no title, but it has the "success" styling. - - - - This message has a title, and the "danger" styling. - - ``` - -
- -
- ##### Result - - - This message has no title, but it has the "success" styling. - - - - This message has a title, and the "danger" styling. - - -
- -
- -#### 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 - -```astro -
-
- - This is column 1. - -
-
- - This is column 2. - -
-
-``` - -##### Result - -
-
- This is column 1. -
-
- This is column 2. -
-
- -# 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](#author-information). -- 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 `` 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: - -```markdown -A summary of the post goes here. - - - ---- - -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.