From efef15fda4f911d0e76963b1a496a7e214fef83c Mon Sep 17 00:00:00 2001 From: Southpaw Date: Mon, 2 Sep 2024 17:05:08 +0100 Subject: [PATCH 01/12] Update README.md --- README.md | 114 +++++++++++++++++++++++++----------------------------- 1 file changed, 53 insertions(+), 61 deletions(-) diff --git a/README.md b/README.md index 17b86884..81786921 100644 --- a/README.md +++ b/README.md @@ -4,88 +4,80 @@ Website for the Quilt Project. ## Contributing -Thanks for contributing to the site! -There's a couple of things worth noting about our infrastructure, which we will cover below. +This site built with [Astro](https://astro.build), [MDX](https://mdxjs.com), and [i18next](https://www.i18next.com). It is hosted on [Cloudflare Pages](https://developers.cloudflare.com/pages/). ### IDE/Editor Choice -For contributors, we recommend using [Visual Studio Code](https://code.visualstudio.com) or [VSCodium](https://vscodium.com/) as your IDE, as it features Astro support via [the official Astro plugin](https://marketplace.visualstudio.com/items?itemName=astro-build.astro-vscode). -Additionally, you would need to install [the MDX plugin](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) to have syntax highlighting for the `.mdx` files, -and [the `vscode-fluent` plugin](https://marketplace.visualstudio.com/items?itemName=macabeus.vscode-fluent) if you need to translate the site or otherwise tinker with Fluent's `.ftl` files. +The simplest editor to use is [Visual Studio Code](https://code.visualstudio.com) (VSCode), because it has official language extensions for [Astro](https://marketplace.visualstudio.com/items?itemName=astro-build.astro-vscode) and [MDX](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx). When you open the repository in VSCode, you will see a popup in the bottom-right corner offering to install some recommended extensions. You can also type `@recommended` in the extension search bar to browse the recommended extensions and manually install the ones you want. -In theory, you can use any editor to your liking that supports the [Language Server Protocol](https://microsoft.github.io/language-server-protocol/), hooked up to the [Astro Language Server](https://github.com/withastro/language-tools/tree/main/packages/language-server) and optionally other LSPs for MDX and Fluent. -Unfortunately as of the date of writing (Sept 11, 2022) no pre-built integrations of the Astro Language Server actually exist, which is why we still recommend using VS Code as your IDE. - -For VSCode, you should see a popup in the bottom right when you open the project with recommended extensions. You can also type `@recommended` in the extensions page to see the recommended extensions: +If you would prefer not to use VSCode, you can use any editor that supports a subset of the following tools, based on what you're doing: -### Running the Dev Server - -To run the development server, you first need to have `npm` installed in your system. Usually this comes pre-installed with [Node.js](https://nodejs.org), so you might want to install that first. +- If you just want to write blog articles or edit pages that are mostly simple text, you only need an editor that supports [Markdown](https://en.wikipedia.org/wiki/Markdown) +- If you want to work with layouts or components, you need an editor with support for .astro files, such as: + - [Sublime Text](https://www.sublimetext.com) with the [Astro extension](https://packagecontrol.io/packages/Astro) + - [Neovim](https://neovim.io) with [tree-sitter-astro](https://github.com/virchau13/tree-sitter-astro) and the [Astro lspconfig](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#astro) + - [JetBrains IntelliJ IDEA Ultimate](https://www.jetbrains.com/idea/) or [WebStorm](https://www.jetbrains.com/webstorm/) with the [Astro extension](https://plugins.jetbrains.com/plugin/20959-astro) +- If you want to work with more complex pages, you may want an editor with support for MDX, though many editors with Markdown support render MDX fairly accurately. +- If you want work with the i18n system, you may want an editor with support for [Fluent](https://projectfluent.org). However, this isn't strictly necessary if you only want to translate the website. -> [!NOTE] -> Only `npm` is regularly used and tested for the site, so you might encounter bugs or incompatibilities using an alternate package manager. - -Once `npm` is installed, clone this repository, navigate into the project folder and run `npm install` to install dependencies: -```sh -$ git clone https://github.com/QuiltMC/quiltmc.org -$ cd quiltmc.org -$ npm install -``` +### Building or running in Dev mode +As mentioned previously, the website is built using Astro, which is written in [TypeScript](https://www.typescriptlang.org). -Once installation is complete, then run `npm run dev` to start the dev server. -The server application should have an output like this: -```sh -$ npm run dev +#### Installing Node.js +Node.js is a cross-platform JavaScript runtime. It can be [installed directly](https://nodejs.org/en), or is likely available for your favourite package manager. -> quiltmc-website@1.0.0 dev -> node csscopy.mjs && astro dev +#### Installing PNPM +We use [PNPM](https://pnpm.io) as our Node.js package manager. It can be installed in the following ways: +- Using NPM (included with Node.js): `npm install -g pnpm` +- Using [a different package manager](https://pnpm.io/installation#using-other-package-managers) - 🚀 astro v1.2.1 started in 56ms +For more options, see [PNPM's docs](https://pnpm.io/installation#on-posix-systems) - ┃ Local http://localhost:3000/ - ┃ Network use --host to expose +#### Setting up the project +Inside the project, install all the required packages using PNPM: +```shell +pnpm i ``` -At this point, open your browser, and you should be able to see the generated site at `http://localhost:3000`. - -As Astro utilizes hot module reloading (HMR), any changes you make would be reflected in the browser quickly. -However, sometimes components and layouts don't get rebuilt with HMR and you might have to restart the Astro server to see your changes, which is easily done by pressing Ctrl+C and rerunning `npm run dev`. - -You're all set! Although, I would recommend reading about [the architecture of this site](ARCHITECTURE.md) before making any changes, to familiarize yourself with the project structure. Have fun contributing! - -#### Cloudflare Pages Dev server - -Some functionalities of the website, such as redirects or functions, use some Cloudflare Pages specific features. -To test these features, you can run the following command: - -```sh -$ npx wrangler pages dev -- npm run dev --host +#### Running the dev server +Astro includes a development server that automatically reloads itself as you change files inside the project. To start it, run `pnpm dev`: ``` +> pnpm dev +15:05:32 [types] Generated 1ms -Make sure to use the url provided by wrangler, as it will be different from the one provided by Astro. It should appear underneath `Worker reloaded!`. - -### Building + astro v4.15.2 ready in 702 ms -To build the site as seen in production, simply run `npm run build`. -Astro will then build the site and emit the output in `dist/`. +┃ Local http://localhost:4321/ +┃ Network use --host to expose -```sh -$ npm run build +15:05:32 watching for file changes... ``` +The dev server builds pages as you visit them to reduce start time, so its performance is worse than the fully built site. +#### Building the site +To build a full copy of the final site: +``` +pnpm build +``` +The site will be built into the `dist` folder. Building the site is a useful way to check that you haven't broken anything without noticing. -To view the built site, you can run `npm run preview`: -```sh -$ npm run preview - -> quiltmc-website@1.0.0 preview -> node csscopy.mjs && astro preview +You can preview the built site using `pnpm astro preview`, but in most cases the only advantage this has over the dev server is performance. - 🚀 astro v1.2.1 started in 2ms +### Previewing with Cloudflare Wrangler +If you need to test Cloudflare Pages-sepcific functionality (such as anything in the `functions` directory), you can preview the site using Cloudflare's [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/) to emulate a Cloudflare Pages deployment. - ┃ Local http://localhost:3000/ - ┃ Network use --host to expose +First, install Wrangler +```shell +pnpm install -g wrangler +``` +Build the site: +```shell +pnpm build +``` +Run the outputted `dist` folder using Wrangler: +``` +wrangler pages dev dist ``` -You can then visit the built site at `http://localhost:3000`. +Unlike the dev server, Wrangler can only preview a site that is fully built. \ No newline at end of file From 16c816c7b9a3b93d931c081b7601da78f9666aae Mon Sep 17 00:00:00 2001 From: Southpaw Date: Tue, 3 Sep 2024 14:31:03 +0100 Subject: [PATCH 02/12] Update ARCHITECTURE.md to reflect the current state of the website. --- ARCHITECTURE.md | 95 +++++++++++++++++++++++++++++++------------------ 1 file changed, 60 insertions(+), 35 deletions(-) diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 36da3ead..29e78f81 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -1,8 +1,19 @@ -# Architecture of This Site - -Contributors should also familiarize themselves with the architecture of this repository, which is best done by taking a look at the folder structure: +# Architecture +quiltmc.org is a [JAMStack](https://jamstack.org/) site, built using [TypeScript](https://typescriptlang.org), [Astro](https://astro.build), and [i18next](https://i18next.com); and hosted on [Cloudflare Pages](https://developers.cloudflare.com/pages/). It is largely a static site, although there is some server-side functionality. +The architecture of the site is explained below in terms of its folder structure: ``` +functions/ + api/ + internal/ + v1/ +public/ + .gpg/ + .well-known/ + assets/ + favicon/ +scripts/ + resources/ src/ components/ atoms/ @@ -17,57 +28,71 @@ src/ ... pages/ util/ -public/ - assets/ - favicon/ ``` -## Source (`src/`) +## Functions (`functions/`) +Although Astro compiles an entirely static site, files in this folder are added by Cloudflare to the deployed site and served dynamically using file-based routing. Most of them are auto-generated files that redirect users to the correct page based on their browser's `Accept-Language` header. Only the `api/` contains manually written functions that are tracked by git. -This folder contains all of the code and content of the site. -As a rule of thumb, you should put all non-assets here. +### `api/` +- `api/internal`: Contains a function that downloads the [template mod](https://github.com/quiltmc/quilt-template-mod) from GitHub for the Mod Generator. This API is not designed to be used by external programs. +- `api/v1`: Contains the public website API. For more information about the available routes and their responses, see https://quiltmc.org/api/ . -### Components (`src/components/`) +## Public (`public/`) +Files in the in the `/public` folder are copied directly to the built site without any processing. They are copied to the root of the site instead of a `public` directory, so they should be referenced without a leading `public` path (`/image.png`, not `/public/image.png`). -The components folder contains components, which are divided into three kinds—atoms, parts and setpieces. +### `_headers` and `_redirects` +Files that Cloudflare Pages uses to send extra headers and HTTP redirects for certain requests. For more information, see the Cloudflare's documentation for [Headers](https://developers.cloudflare.com/pages/configuration/headers/) and [Redirects](https://developers.cloudflare.com/pages/configuration/redirects/). -Atoms (available under `@atoms`) are simple, reusable components that follow the Unix philosophy—do one thing, and do one thing well. -They are practically found everywhere, often used as a building block of pages, parts, setpieces, and so on. Examples of atoms include buttons and messages. +### `.gpg/` +Holds public GPG keys for the Infrastructure Team and the Admin Board. -Parts (`@parts`) are more complex components than atoms, and are often specialized for one purpose or for a single page—for example, the grid of launchers in the install page is a single part, which consists of several `InstallerButton`s, which are atoms. +### `.well-known/security.txt` +Outlines our security policy for reporting exploits and vulnerabilities using the proposed [security.txt standard](https://securitytxt.org). -Setpieces (`@setpieces`) are very complex structures that typically provide a large chunk of functionality of a page, such as the navbar, the footer and the sidebar. -These gigantic components are intended to be used alone in pages, and not in other components. +### `api/` +Static routes for the API, including the OpenAPI specification and the incompatible mods JSON file. -### Data (`src/data/`, `@data`) +### `assets/` +Static files used in various places on the website: +- `css/`: Custom CSS files. +- `img/`: Images used around the site. +- `license-templates/`: Templates for software licenses used as part of the Mod Generator. -The data folder contains some TypeScript files for storing some common variables used throughout the site, such as links, account names, localization settings, etc. +### `favicon/` +Various incarnations of the site's favicon. -### Layouts (`src/layouts/`, `@layouts`) +## Scripts (`scripts/`) +This folder contains scripts that are run during the build process of the site: They fetch and cache data from GitHub and [PluralKit](https://pluralkit.me) to use in the [teams page](https://quiltmc.org/about/teams) and change logs, and they generate functions for routing the user based on their requested language (see "Functions"). -This folder contains every layout of the site, used by all pages of the site. Nothing much to say about that. +Most functionality is in `preprocess.mjs`, the other scripts are utilities that it imports. `resources` contains the base code used to generate each auto-generated function. `clean` clears cached PluralKit data, and can be invoked using `pnpm clean`. -### Locales (`src/locales/`) +## Source (`src/`) +This folder contains all the files that are processed by Astro when the site is built. Many of its sub-folders have [TypeScript import path aliases](https://www.typescriptlang.org/docs/handbook/modules/reference.html#paths) which you can use instead of relative paths in import statements. These are prefixed with an `@` and inside (parentheses) -This folder contains the translated strings used in the site. Under this folder, each locale gets its own folder—`en/` for English, `zh/` for Chinese, etc. -Under that, you will see a bunch of `.flt` files—they are [Fluent](https://projectfluent.org) files, parsed and substituted into the site. +### Components (`src/components/`) +Small pieces of code that form parts of larger pages. They are split into three categories: -It is worth noting that most of the site's text doesn't get translated this way—as you will see, we only use Fluent for short and common strings. -Long paragraphs of text remain in Astro and Markdown files, which need to be translated as Astro and Markdown files. +**Atoms** (`@atoms`): Fundamental, reusable components that are designed to each do one thing well. They are widely used, often as building blocks for more complex pages. -### Pages (`src/pages/`) +**Parts** (`@parts`): More complex components that are specialised for a specific page or set piece. For example, the cards on the team page and the home page. -Pretty self-explanatory—the main content of this site. Edit this section if you're looking to add content, to fix a typo, etc. +**Set Pieces** (`@setpieces`): Large components that form a part of many pages, such as the nav bar, header, and footer. Set Pieces are the highest-level components and should not be reused inside of other components. -### Utilities (`src/util`, `@util`) +### Data (`src/data`, `@data`) +This folder contains type definitions and objects for various pieces of data used elsewhere in the site. Of particular interest is `TeamData.mjs`, which contains the information used to generate the info cards on the [Team Listings page](https://quiltmc.org/about/teams). -This folder contains a bunch of TypeScript files containing common functions for doing tasks like localizing paths, getting the edit date of a page, fetching launcher updates, etc. +### Layouts (`src/layouts/`, `@layouts`) +While the content of pages is stored in `src/pages`, this folder stores their layouts separately, which makes translating the pages easier, and allows the same layouts to be shared by pages in multiple languages. Some layouts are used by multiple pages, such as `Page.astro` and `Post.astro`; while others are dedicated to a single page, such as `Home.astro` and `InstallPage.astro`. Some layouts build on top of others others: for example,`LatestVersions.astro` uses `Page.astro`. -## Public (`public/`) +### Locales (`src/locales/`) +This folder contains [Fluent](https://projectfluent.org) files with translations for terms and phrases that are commonly used throughout the site. Not all localization occurs in this folder: Only short words and phrases that are used in multiple places. Each language has a folder with its language code, containing files with phrases to be translated. + +### Pages (`src/pages/`) +This folder stores the content of all the pages on the site, mostly in Markdown or [MDX](https://mdxjs.com) files, depending on the complexity of the page. Pages are stored in a folder specific to their language: English pages in `en/` and so on. Some special pages are excepted from this, for example, `api.astro`. -This folder stores assets that can be included in the built site *verbatim*—these files are not processed at all while building—good for images, processed stylesheets, favicons, and more! +This folder is special to Astro: It is used to generate the routing and structure of the final site. Each file corresponds to a page, and they are structured in the same way that the site will be when it is generated, so `src/pages/api.astro` becomes `https://quiltmc.org/api`. Files called `index` are named after the folder they are inside, so `src/pages/en/about/index.astro` becomes `https://quiltmc.org/en/about/`. JavaScript and TypeScript files in this folder are executed at build time to generate a page in the final site, for example, `src/pages/feed.xml.js` generates the RSS feed at https://quiltmc.org/feed.xml . -Minutiae: -- Note that in the built site, the assets stored here are directly placed under the root path: for example, a file at `public/image.png` should be accessed with the path `/image.png`. -- Files under `public/assets/css/` are currently precompiled from SCSS files from the `quilt-bulma` package. This may change in the future! -- We currently bundle a CSS/WebFonts copy of Font Awesome 6 Free under `public/assets/fontawesome/` as a fallback option for users who have disabled JavaScript. This again, may change in the future. +Some files are surrounded by brackets, such as `src/en/blog/[page].astro`. These files generate multiple pages using Astro's [Dynamic Routes](https://docs.astro.build/en/guides/routing/#dynamic-routes). + +### Utilities (`src/util`, `@util`) +This folder contains simple utility functions for things like localizing paths, sorting lists, and getting the last modified date of a page. From a91fe2f07ec0e3f10f06c4c40b643c731a05abd9 Mon Sep 17 00:00:00 2001 From: Southpaw Date: Tue, 3 Sep 2024 14:36:11 +0100 Subject: [PATCH 03/12] Add warning to LOCALIZATION.md about upcoming i18n revisions. --- LOCALIZATION.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/LOCALIZATION.md b/LOCALIZATION.md index 47c21741..2e5e0d7d 100644 --- a/LOCALIZATION.md +++ b/LOCALIZATION.md @@ -1,5 +1,10 @@ # Localization Guide +> [!WARNING] +> The website is currently undergoing major revisions to its internal workings following an upgrade to Astro 4. These revisions may include changes to the localization system. +> +> For the time being, attempting to translate the site is not recommended. + Welcome! In this guide, we will cover how the site's localization system works, and how you can contribute translations of the site. ## Setup From 68d80ce7bed8876ce40a969651b5deb68050fa2d Mon Sep 17 00:00:00 2001 From: Southpaw Date: Tue, 3 Sep 2024 17:55:41 +0100 Subject: [PATCH 04/12] =?UTF-8?q?Add=20=E2=80=9CCommon=20Contributions?= =?UTF-8?q?=E2=80=9D=20section.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 49 ++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 48 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 81786921..d821bc86 100644 --- a/README.md +++ b/README.md @@ -80,4 +80,51 @@ Run the outputted `dist` folder using Wrangler: wrangler pages dev dist ``` -Unlike the dev server, Wrangler can only preview a site that is fully built. \ No newline at end of file +Unlike the dev server, Wrangler can only preview a site that is fully built. + +### Common Contributions +Instructions for making various common types of contributions. + +#### Adding an Incompatible Mod +Open the `incompatible-mods.json` file in `public/api/v1/incompatible-mods.json` and add a new entry at the bottom of the list. + +Your entry must have the following fields: +- `"ids":` - A list of mod IDs that are affected. +- `"Name":` - The full name of the affected mod. +- `"type":` - The type of incompatibility. Can be one of the following: + - `"GAME"` - Crashes or breaks the vanilla game. + - `"OTHERS"` - Breaks one or more other mods. + - `"SELF"` - Breaks itself. + - `"WORKAROUND"` - Has a workaround that allows it to function properly. +- `"Status":` - How close the incompatibility is to being fixed. Can be one of the following: + - `"BLOCKED"` - The mod authors are aware of the issue, but a fix is blocked by an external factor. + - `"IN_PROGRESS"` - The mod authors are implementing a fix. + - `"NO_ANSWER"` - The issue has been reported, but the mod authors have not responded. + - `"ON_HOLD"` - The mod authors are waiting to implement or release the fix. + - `"UNKNOWN"` - The issue hasn't been reported to the mod authors, or you can't find a report. + - `"WON'T FIX"` - The issue has been reported, but the mod authors refuse to fix it. +- `"tracking":` - A link to the report tracking the incompatibility, for example, a GitHub issue. Set to `"UNKNOWN"` if you don't know. +- `"notes":` (optional) - Any other notes, for example, the a known workaround. + +#### Writing a Blog Post +Create a new Markdown file in `src/pages/en/blog`, named with the current date and a shortened version of the title. The date should be in the format `yyyy-mm-dd`, and the title should be in lowercase and separated by hyphens (`-`). A full file might be `2024-03-09-example-post.md`. + +At the top of the file, you need to add *front matter*, which is metadata about the post written in YAML. The front matter for blog post looks like this: +```yaml +--- +title: "An Example Title" # The full title of the post +date: 2024-09-03 20:00:00 -00:00 # The date, time, and timezone that the post was written, relative to UTC. It is best practice to give the time in UTC and use an offset of -00:00, as shown. +authors: # A list of one or more authors +- Pineapple +layout: /src/layouts/Post.astro # This tells Astro what layout to use for the page, and should always be the same. +--- +``` +Write a short first paragraph, then insert two lines, put ``, then two more lines. For example: +``` +A succinct first paragraph. + + + +More text here. +``` +This tells the website what to include in the short preview that goes on the home page and in the list of blog posts. From here on, you can keep writing Markdown to your heart's content. Syntax highlighting in code blocks is also supported. From ed5299f55d76f37bb3cf0d174cd904fa8285d538 Mon Sep 17 00:00:00 2001 From: Southpaw Date: Tue, 3 Sep 2024 18:17:34 +0100 Subject: [PATCH 05/12] Clarify when setting up a development environment is necessary. --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index d821bc86..744fc27f 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,6 @@ Website for the Quilt Project. This site built with [Astro](https://astro.build), [MDX](https://mdxjs.com), and [i18next](https://www.i18next.com). It is hosted on [Cloudflare Pages](https://developers.cloudflare.com/pages/). ### IDE/Editor Choice - The simplest editor to use is [Visual Studio Code](https://code.visualstudio.com) (VSCode), because it has official language extensions for [Astro](https://marketplace.visualstudio.com/items?itemName=astro-build.astro-vscode) and [MDX](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx). When you open the repository in VSCode, you will see a popup in the bottom-right corner offering to install some recommended extensions. You can also type `@recommended` in the extension search bar to browse the recommended extensions and manually install the ones you want. @@ -22,8 +21,8 @@ If you would prefer not to use VSCode, you can use any editor that supports a su - If you want to work with more complex pages, you may want an editor with support for MDX, though many editors with Markdown support render MDX fairly accurately. - If you want work with the i18n system, you may want an editor with support for [Fluent](https://projectfluent.org). However, this isn't strictly necessary if you only want to translate the website. -### Building or running in Dev mode -As mentioned previously, the website is built using Astro, which is written in [TypeScript](https://www.typescriptlang.org). +### Setting up a development environment +As mentioned previously, the website is built using Astro, which is written in [TypeScript](https://www.typescriptlang.org), so you will need a Node.js-compatible JavaScript runtime in order to build and run it for development. If you only making a simple contribution, such as an [incompatible mod](#adding-an-incompatible-mod) or a [blog post](#writing-a-blog-post), setting up a development environment isn't strictly necessary: A preview version of the site will be built when you submit a pull request to ensure that everything works as expected. #### Installing Node.js Node.js is a cross-platform JavaScript runtime. It can be [installed directly](https://nodejs.org/en), or is likely available for your favourite package manager. @@ -33,7 +32,7 @@ We use [PNPM](https://pnpm.io) as our Node.js package manager. It can be install - Using NPM (included with Node.js): `npm install -g pnpm` - Using [a different package manager](https://pnpm.io/installation#using-other-package-managers) -For more options, see [PNPM's docs](https://pnpm.io/installation#on-posix-systems) +For more options, see [PNPM's docs](https://pnpm.io/installation). #### Setting up the project Inside the project, install all the required packages using PNPM: @@ -55,6 +54,7 @@ Astro includes a development server that automatically reloads itself as you cha 15:05:32 watching for file changes... ``` The dev server builds pages as you visit them to reduce start time, so its performance is worse than the fully built site. + #### Building the site To build a full copy of the final site: ``` From 590d463c1c7bc8667da6943331de0f56ab960ba1 Mon Sep 17 00:00:00 2001 From: Southpaw Date: Tue, 3 Sep 2024 19:06:26 +0100 Subject: [PATCH 06/12] README: Add section for updating your team member card. --- README.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/README.md b/README.md index 744fc27f..6a38254e 100644 --- a/README.md +++ b/README.md @@ -128,3 +128,24 @@ A succinct first paragraph. More text here. ``` This tells the website what to include in the short preview that goes on the home page and in the list of blog posts. From here on, you can keep writing Markdown to your heart's content. Syntax highlighting in code blocks is also supported. + +#### Updating your team member card +If you are a part of one of Quilt's developer or community teams, you likely have a card on the website's [Team Listings](https://quiltmc.org/about/teams) page. The data inside the cards on this page is built from the `TeamData.mjs` file in `src/data/`. + +Each team member has an object in this file with data about them. The section(s) of the page that you're listed in is based on which teams you're in on GitHub. + +You can change the following data to customise your card: +- `name:` - The name at the top of your card. It can be anything you want. +- `discord:` - Your Discord username. +- `github:` - Your GitHub username. This is used to identify which teams you're in on GitHub. +- `avatar:` - This is a URL to any image you like. For best results, it should be square and not too large. You can put a file in `public/assets/team/images` to have it hosted on the website, or use any other image URL you like. +- `description:` (optional) - A sentence or small paragraph about who you are. +- `links:` (optional) - A list of links to your various webpages or social media profiles. Each link is represented by the following object: + - `icon`: An icon that represents the link. You can choose from the icon sets [CoreUI Brands](https://icon-sets.iconify.design/cib/?keyword=cib), or (`cib:`), Material Design Icons (`mdi:`) [Material Design Icons](https://icon-sets.iconify.design/cib/?keyword=mdi) (`material-symbols:`); or use our custom icons for CurseForge (`curseforge`) and Modrinth (`modrinth-small`). When using an icon from an icon set (as opposed to a custom one), you must prefix the icon name with the name of the icon set, for example, `cib:youtube` to use the `youtube` icon from CoreUI Brands. + - `url`: The link to the webpage. +- `systemMembers:` (optional) - This field is intended for plural systems to display each of their members. It has a few possible values: + - `"---"` will show you as being a plural system with your members hidden. + - A [PluralKit](https://pluralkit.me) system ID will automatically fetch and display the names and avatars of all the public members of that system. + - You can manually build a system using a list of the following objects: + - `name:` The name of the system member. + - `icon:` - An avatar for the member. You can use any URL you want, or host an image on this site in `public/assets/team/images//`. From a0d13579e2b2d11ff94eef9b1dda3536560c351a Mon Sep 17 00:00:00 2001 From: Southpaw Date: Tue, 3 Sep 2024 19:24:53 +0100 Subject: [PATCH 07/12] Spelling and formatting improvements --- README.md | 44 ++++++++++++++++++++++++-------------------- 1 file changed, 24 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index 6a38254e..0758fdf4 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,8 @@ Website for the Quilt Project. This site built with [Astro](https://astro.build), [MDX](https://mdxjs.com), and [i18next](https://www.i18next.com). It is hosted on [Cloudflare Pages](https://developers.cloudflare.com/pages/). +If you get stuck or have questions, please join us in the [`#Website`](https://discord.com/channels/817576132726620200/1103986836415713300) thread on our [Discord server](https://discord.quiltmc.org). + ### IDE/Editor Choice The simplest editor to use is [Visual Studio Code](https://code.visualstudio.com) (VSCode), because it has official language extensions for [Astro](https://marketplace.visualstudio.com/items?itemName=astro-build.astro-vscode) and [MDX](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx). When you open the repository in VSCode, you will see a popup in the bottom-right corner offering to install some recommended extensions. You can also type `@recommended` in the extension search bar to browse the recommended extensions and manually install the ones you want. @@ -15,14 +17,14 @@ If you would prefer not to use VSCode, you can use any editor that supports a su - If you just want to write blog articles or edit pages that are mostly simple text, you only need an editor that supports [Markdown](https://en.wikipedia.org/wiki/Markdown) - If you want to work with layouts or components, you need an editor with support for .astro files, such as: - - [Sublime Text](https://www.sublimetext.com) with the [Astro extension](https://packagecontrol.io/packages/Astro) - - [Neovim](https://neovim.io) with [tree-sitter-astro](https://github.com/virchau13/tree-sitter-astro) and the [Astro lspconfig](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#astro) - - [JetBrains IntelliJ IDEA Ultimate](https://www.jetbrains.com/idea/) or [WebStorm](https://www.jetbrains.com/webstorm/) with the [Astro extension](https://plugins.jetbrains.com/plugin/20959-astro) + - [Sublime Text](https://www.sublimetext.com) with the [Astro extension](https://packagecontrol.io/packages/Astro) + - [Neovim](https://neovim.io) with [tree-sitter-astro](https://github.com/virchau13/tree-sitter-astro) and the [Astro lspconfig](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#astro) + - JetBrains [IntelliJ IDEA Ultimate](https://www.jetbrains.com/idea/) or [WebStorm](https://www.jetbrains.com/webstorm/) with the [Astro extension](https://plugins.jetbrains.com/plugin/20959-astro) - If you want to work with more complex pages, you may want an editor with support for MDX, though many editors with Markdown support render MDX fairly accurately. - If you want work with the i18n system, you may want an editor with support for [Fluent](https://projectfluent.org). However, this isn't strictly necessary if you only want to translate the website. ### Setting up a development environment -As mentioned previously, the website is built using Astro, which is written in [TypeScript](https://www.typescriptlang.org), so you will need a Node.js-compatible JavaScript runtime in order to build and run it for development. If you only making a simple contribution, such as an [incompatible mod](#adding-an-incompatible-mod) or a [blog post](#writing-a-blog-post), setting up a development environment isn't strictly necessary: A preview version of the site will be built when you submit a pull request to ensure that everything works as expected. +As mentioned previously, the website is built using Astro, which is written in [TypeScript](https://www.typescriptlang.org), so you will need a Node.js-compatible JavaScript runtime in order to build and run it for development. If you only making a simple contribution, such as an [incompatible mod](#adding-an-incompatible-mod) or a [blog post](#writing-a-blog-post), setting up a development environment isn't essential: A preview version of the site will be built when you submit a pull request to ensure that everything works as expected. #### Installing Node.js Node.js is a cross-platform JavaScript runtime. It can be [installed directly](https://nodejs.org/en), or is likely available for your favourite package manager. @@ -60,12 +62,12 @@ To build a full copy of the final site: ``` pnpm build ``` -The site will be built into the `dist` folder. Building the site is a useful way to check that you haven't broken anything without noticing. +The site will be built into the `dist/` folder. Building the site is a useful way to check that you haven't broken anything without noticing. You can preview the built site using `pnpm astro preview`, but in most cases the only advantage this has over the dev server is performance. ### Previewing with Cloudflare Wrangler -If you need to test Cloudflare Pages-sepcific functionality (such as anything in the `functions` directory), you can preview the site using Cloudflare's [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/) to emulate a Cloudflare Pages deployment. +If you need to test Cloudflare Pages-specific functionality (such as anything in the `functions/` directory), you can preview the site using Cloudflare's [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/)to emulate a Cloudflare Pages deployment. First, install Wrangler ```shell @@ -80,7 +82,7 @@ Run the outputted `dist` folder using Wrangler: wrangler pages dev dist ``` -Unlike the dev server, Wrangler can only preview a site that is fully built. +Unlike Astro's dev server, Wrangler can only preview a site that is fully built. ### Common Contributions Instructions for making various common types of contributions. @@ -89,27 +91,28 @@ Instructions for making various common types of contributions. Open the `incompatible-mods.json` file in `public/api/v1/incompatible-mods.json` and add a new entry at the bottom of the list. Your entry must have the following fields: -- `"ids":` - A list of mod IDs that are affected. + +- `"ids":` - A list of mod IDs that are affected. - `"Name":` - The full name of the affected mod. - `"type":` - The type of incompatibility. Can be one of the following: - - `"GAME"` - Crashes or breaks the vanilla game. - - `"OTHERS"` - Breaks one or more other mods. - - `"SELF"` - Breaks itself. + - `"GAME"` - Crashes or breaks the vanilla game. + - `"OTHERS"` - Breaks one or more other mods. + - `"SELF"` - Breaks itself. - `"WORKAROUND"` - Has a workaround that allows it to function properly. - `"Status":` - How close the incompatibility is to being fixed. Can be one of the following: - - `"BLOCKED"` - The mod authors are aware of the issue, but a fix is blocked by an external factor. - - `"IN_PROGRESS"` - The mod authors are implementing a fix. - - `"NO_ANSWER"` - The issue has been reported, but the mod authors have not responded. - - `"ON_HOLD"` - The mod authors are waiting to implement or release the fix. - - `"UNKNOWN"` - The issue hasn't been reported to the mod authors, or you can't find a report. - - `"WON'T FIX"` - The issue has been reported, but the mod authors refuse to fix it. + - `"BLOCKED"` - The mod authors are aware of the issue, but a fix is blocked by an external factor. + - `"IN_PROGRESS"` - The mod authors are implementing a fix. + - `"NO_ANSWER"` - The issue has been reported, but the mod authors have not responded. + - `"ON_HOLD"` - The mod authors are waiting to implement or release the fix. + - `"UNKNOWN"` - The issue hasn't been reported to the mod authors, or you can't find a report. + - `"WON'T FIX"` - The issue has been reported, but the mod authors refuse to fix it. - `"tracking":` - A link to the report tracking the incompatibility, for example, a GitHub issue. Set to `"UNKNOWN"` if you don't know. - `"notes":` (optional) - Any other notes, for example, the a known workaround. #### Writing a Blog Post -Create a new Markdown file in `src/pages/en/blog`, named with the current date and a shortened version of the title. The date should be in the format `yyyy-mm-dd`, and the title should be in lowercase and separated by hyphens (`-`). A full file might be `2024-03-09-example-post.md`. +Create a new Markdown file in `src/pages/en/blog`, named with the current date and a shortened version of the title. The date should be in the format `yyyy-mm-dd`, and the title should be in lowercase and separated by hyphens (`-`), for example, `2024-03-09-example-post.md`. -At the top of the file, you need to add *front matter*, which is metadata about the post written in YAML. The front matter for blog post looks like this: +At the top of the file, you need to add *front matter*, which is metadata written in YAML. The front matter for a blog post looks like this: ```yaml --- title: "An Example Title" # The full title of the post @@ -135,13 +138,14 @@ If you are a part of one of Quilt's developer or community teams, you likely hav Each team member has an object in this file with data about them. The section(s) of the page that you're listed in is based on which teams you're in on GitHub. You can change the following data to customise your card: + - `name:` - The name at the top of your card. It can be anything you want. - `discord:` - Your Discord username. - `github:` - Your GitHub username. This is used to identify which teams you're in on GitHub. - `avatar:` - This is a URL to any image you like. For best results, it should be square and not too large. You can put a file in `public/assets/team/images` to have it hosted on the website, or use any other image URL you like. - `description:` (optional) - A sentence or small paragraph about who you are. - `links:` (optional) - A list of links to your various webpages or social media profiles. Each link is represented by the following object: - - `icon`: An icon that represents the link. You can choose from the icon sets [CoreUI Brands](https://icon-sets.iconify.design/cib/?keyword=cib), or (`cib:`), Material Design Icons (`mdi:`) [Material Design Icons](https://icon-sets.iconify.design/cib/?keyword=mdi) (`material-symbols:`); or use our custom icons for CurseForge (`curseforge`) and Modrinth (`modrinth-small`). When using an icon from an icon set (as opposed to a custom one), you must prefix the icon name with the name of the icon set, for example, `cib:youtube` to use the `youtube` icon from CoreUI Brands. + - `icon`: An icon that represents the link. You can choose from the icon sets [CoreUI Brands](https://icon-sets.iconify.design/cib/?keyword=cib)(`cib:`), [Material Design Icons](https://icon-sets.iconify.design/cib/?keyword=mdi) (`mdi:`), or [Material Symbols](https://icon-sets.iconify.design/material-symbols) (`material-symbols:`); or use our custom icons for CurseForge (`curseforge`) and Modrinth (`modrinth-small`). When using an icon from an icon set (as opposed to a custom one), you must prefix the icon name with the name of the icon set, for example, `cib:youtube` to use the `youtube` icon from CoreUI Brands. - `url`: The link to the webpage. - `systemMembers:` (optional) - This field is intended for plural systems to display each of their members. It has a few possible values: - `"---"` will show you as being a plural system with your members hidden. From b592eac2eee7d85ee29bb0441fa0d543a90546db Mon Sep 17 00:00:00 2001 From: Southpaw Date: Tue, 3 Sep 2024 21:12:37 +0100 Subject: [PATCH 08/12] =?UTF-8?q?Link=20to=20Astro=E2=80=99s=20documentati?= =?UTF-8?q?on?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 0758fdf4..0da6cbe2 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ Website for the Quilt Project. ## Contributing -This site built with [Astro](https://astro.build), [MDX](https://mdxjs.com), and [i18next](https://www.i18next.com). It is hosted on [Cloudflare Pages](https://developers.cloudflare.com/pages/). +This site built with [Astro](https://astro.build), [MDX](https://mdxjs.com), and [i18next](https://www.i18next.com). It is hosted on [Cloudflare Pages](https://developers.cloudflare.com/pages/). If you want to get more familiar with Astro, you can read [its documentation](https://docs.astro.build). If you get stuck or have questions, please join us in the [`#Website`](https://discord.com/channels/817576132726620200/1103986836415713300) thread on our [Discord server](https://discord.quiltmc.org). From 9f455ddca5eee283514cf972ef92f7f59fc881f1 Mon Sep 17 00:00:00 2001 From: Southpaw Date: Tue, 3 Sep 2024 21:18:47 +0100 Subject: [PATCH 09/12] Mention ARCHITECTURE.md --- README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/README.md b/README.md index 0da6cbe2..90662940 100644 --- a/README.md +++ b/README.md @@ -84,6 +84,9 @@ wrangler pages dev dist Unlike Astro's dev server, Wrangler can only preview a site that is fully built. +### Architecture +For a detailed explanation of how the repository is laid out, see [`ARCHITECTURE.md`](ARCHITECTURE.md) + ### Common Contributions Instructions for making various common types of contributions. From f9cf23461160294219e5b6e69a8c0e1b086ce7bd Mon Sep 17 00:00:00 2001 From: Southpaw Date: Mon, 9 Sep 2024 13:17:02 +0100 Subject: [PATCH 10/12] Fix indentation issue --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 90662940..1f7e0424 100644 --- a/README.md +++ b/README.md @@ -18,8 +18,8 @@ If you would prefer not to use VSCode, you can use any editor that supports a su - If you just want to write blog articles or edit pages that are mostly simple text, you only need an editor that supports [Markdown](https://en.wikipedia.org/wiki/Markdown) - If you want to work with layouts or components, you need an editor with support for .astro files, such as: - [Sublime Text](https://www.sublimetext.com) with the [Astro extension](https://packagecontrol.io/packages/Astro) - - [Neovim](https://neovim.io) with [tree-sitter-astro](https://github.com/virchau13/tree-sitter-astro) and the [Astro lspconfig](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#astro) - - JetBrains [IntelliJ IDEA Ultimate](https://www.jetbrains.com/idea/) or [WebStorm](https://www.jetbrains.com/webstorm/) with the [Astro extension](https://plugins.jetbrains.com/plugin/20959-astro) + - [Neovim](https://neovim.io) with [tree-sitter-astro](https://github.com/virchau13/tree-sitter-astro) and the [Astro lspconfig](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#astro) + - JetBrains [IntelliJ IDEA Ultimate](https://www.jetbrains.com/idea/) or [WebStorm](https://www.jetbrains.com/webstorm/) with the [Astro extension](https://plugins.jetbrains.com/plugin/20959-astro) - If you want to work with more complex pages, you may want an editor with support for MDX, though many editors with Markdown support render MDX fairly accurately. - If you want work with the i18n system, you may want an editor with support for [Fluent](https://projectfluent.org). However, this isn't strictly necessary if you only want to translate the website. @@ -50,7 +50,7 @@ Astro includes a development server that automatically reloads itself as you cha astro v4.15.2 ready in 702 ms -┃ Local http://localhost:4321/ +┃ Local http://localhost:4321/ ┃ Network use --host to expose 15:05:32 watching for file changes... From 3b62ecfba9752e396a94f0b73d955b073e027551 Mon Sep 17 00:00:00 2001 From: Southpaw Date: Mon, 9 Sep 2024 13:22:23 +0100 Subject: [PATCH 11/12] Fix incompatible mod schema typo --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 1f7e0424..09ff0c46 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ The simplest editor to use is [Visual Studio Code](https://code.visualstudio.com If you would prefer not to use VSCode, you can use any editor that supports a subset of the following tools, based on what you're doing: -- If you just want to write blog articles or edit pages that are mostly simple text, you only need an editor that supports [Markdown](https://en.wikipedia.org/wiki/Markdown) +- If you just want to write blog articles or edit pages that are mostly simple text, you only need an editor that supports [Markdown](https://en.wikipedia.org/wiki/Markdown). - If you want to work with layouts or components, you need an editor with support for .astro files, such as: - [Sublime Text](https://www.sublimetext.com) with the [Astro extension](https://packagecontrol.io/packages/Astro) - [Neovim](https://neovim.io) with [tree-sitter-astro](https://github.com/virchau13/tree-sitter-astro) and the [Astro lspconfig](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#astro) @@ -108,7 +108,7 @@ Your entry must have the following fields: - `"NO_ANSWER"` - The issue has been reported, but the mod authors have not responded. - `"ON_HOLD"` - The mod authors are waiting to implement or release the fix. - `"UNKNOWN"` - The issue hasn't been reported to the mod authors, or you can't find a report. - - `"WON'T FIX"` - The issue has been reported, but the mod authors refuse to fix it. + - `"WONT_FIX"` - The issue has been reported, but the mod authors refuse to fix it. - `"tracking":` - A link to the report tracking the incompatibility, for example, a GitHub issue. Set to `"UNKNOWN"` if you don't know. - `"notes":` (optional) - Any other notes, for example, the a known workaround. From adde2493e5be3a8df35601e60261a402f947ffac Mon Sep 17 00:00:00 2001 From: Southpaw <44805409+Southpaw1496@users.noreply.github.com> Date: Mon, 9 Sep 2024 13:29:20 +0100 Subject: [PATCH 12/12] Apply ixorai's suggestion Co-authored-by: ix0rai --- ARCHITECTURE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 29e78f81..0c916cad 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -62,7 +62,7 @@ Static files used in various places on the website: Various incarnations of the site's favicon. ## Scripts (`scripts/`) -This folder contains scripts that are run during the build process of the site: They fetch and cache data from GitHub and [PluralKit](https://pluralkit.me) to use in the [teams page](https://quiltmc.org/about/teams) and change logs, and they generate functions for routing the user based on their requested language (see "Functions"). +This folder contains scripts that are run during the build process of the site: They fetch and cache data from GitHub and [PluralKit](https://pluralkit.me) to use in the [teams page](https://quiltmc.org/about/teams) and [changelogs](https://quiltmc.org/en/changelog/), and they generate functions for routing the user based on their requested language (see "Functions"). Most functionality is in `preprocess.mjs`, the other scripts are utilities that it imports. `resources` contains the base code used to generate each auto-generated function. `clean` clears cached PluralKit data, and can be invoked using `pnpm clean`.