Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs improvements #249

Merged
merged 13 commits into from
Sep 9, 2024
95 changes: 60 additions & 35 deletions ARCHITECTURE.md
Original file line number Diff line number Diff line change
@@ -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/
Expand All @@ -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").

Southpaw1496 marked this conversation as resolved.
Show resolved Hide resolved
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.
5 changes: 5 additions & 0 deletions LOCALIZATION.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down
Loading
Loading