modrinth · tdgao · Mar 18, 2026 · Mar 18, 2026 · Mar 18, 2026 · Mar 18, 2026
diff --git a/README.md b/README.md
@@ -15,10 +15,10 @@ If you're not a developer and you've stumbled upon this repository, you can acce
 
 ## Development
 
-This repository contains two primary packages. For detailed development information, please refer to their respective READMEs:
+This repository contains two primary packages. For detailed development information, please refer to their respective guides:
 
-- [Web Interface](apps/frontend/README.md)
-- [Desktop App](apps/app/README.md)
+- [Website frontend](https://docs.modrinth.com/contributing/knossos/)
+- [Desktop app](https://docs.modrinth.com/contributing/theseus/)
 
 ## Contributing
 

diff --git a/apps/docs/src/content/docs/contributing/daedalus.md b/apps/docs/src/content/docs/contributing/daedalus.md
@@ -1,4 +1,15 @@
 ---
 title: Daedalus (Metadata service)
 description: Guide for contributing to Modrinth's frontend
+sidebar:
+  order: 5
 ---
+
+Daedalus is a powerful tool which queries and generates metadata for the Minecraft (and other games in the future!) game
+and mod loaders for:
+
+- Performance (Serving static files can be easily cached and is extremely quick)
+- Ease for Launcher Devs (Metadata is served in an easy to query and use format)
+- Reliability (Provides a versioning system which ensures no breakage with updates)
+
+Daedalus supports the original Minecraft data and reposting for the Forge, Fabric, Quilt, and NeoForge loaders.
diff --git a/apps/docs/src/content/docs/contributing/docs.md b/apps/docs/src/content/docs/contributing/docs.md
@@ -17,7 +17,7 @@ pnpm run docs:dev
 
 When ready, you will have a hot-reloading environment of the docs site running on port 4321.
 
-#### Ready to open a PR?
+## Ready to open a PR?
 
 While there is no linting requirement on Docs, we do ask that you quickly check your writing before contributing.
 

diff --git a/apps/docs/src/content/docs/contributing/getting-started.md b/apps/docs/src/content/docs/contributing/getting-started.md
@@ -9,32 +9,16 @@ sidebar:
 
 Every public-facing aspect of Modrinth, including everything from our [API/backend][labrinth] and [frontend][knossos] to our [Gradle plugin][minotaur] and [launcher][theseus], is released under free and open source licenses on [GitHub]. As such, we love contributions from community members! Before proceeding to do so, though, there are a number of things you'll want to keep in mind throughout the process, as well as some details specific to certain projects.
 
-## Things to keep in mind
-
-### Consult people on Discord
-
-There are a number of reasons to want to consult with people on our [Discord] before making a pull request. For example, if you're not sure whether something is a good idea or not, if you're not sure how to implement something, or if you can't get something working, these would all be good opportunities to create a thread in the `#development` forum channel.
-
-If you intend to work on new features, to make significant codebase changes, or to make UI/design changes, please open a discussion thread first to ensure your work is put to its best use.
-
-### Don't get discouraged
-
-At times, pull requests may be rejected or left unmerged for a variation of reasons. Don't take it personally, and don't get discouraged! Sometimes a contribution just isn't the right fit for the time, or it might have just been lost in the mess of other things to do. Remember, the core Modrinth team are often busy, whether it be on a specific project/task or on external factors such as offline responsibilities. It all falls back to the same thing: don't get discouraged!
-
-### Code isn't the only way to contribute
-
-You don't need to know how to program to contribute to Modrinth. Quality assurance, supporting the community, coming up with feature ideas, and making sure your voice is heard in public decisions are all great ways to contribute to Modrinth. If you find bugs, reporting them on the appropriate issue tracker is your responsibility; however, remember that potential security breaches and exploits must instead be reported in accordance with our [security policy](https://modrinth.com/legal/security).
-
-## Project-specific details
+## Development
 
 If you wish to contribute code to a specific project, here's the place to start. Most of Modrinth is written in the [Rust language](https://www.rust-lang.org), but some things are written in other languages/frameworks like [Nuxt.js](https://nuxtjs.org) or Java.
 
 Most of Modrinth's code is in our monorepo, which you can find [here](https://github.com/modrinth/code). Our monorepo is powered by [Turborepo](https://turborepo.org).
 
 Follow the project-specific instructions below to get started:
 
-- [Knossos (frontend)](/contributing/knossos)
-- [Theseus (Modrinth App)](/contributing/theseus)
+- [Modrinth Website](/contributing/knossos)
+- [Modrinth App](/contributing/theseus)
 - [Minotaur (Gradle plugin)](/contributing/minotaur)
 - [Labrinth (API/backend)](/contributing/labrinth)
 - [Daedalus (Metadata service)](/contributing/daedalus)
@@ -49,3 +33,50 @@ Follow the project-specific instructions below to get started:
 [docs]: https://github.com/modrinth/code/tree/main/apps/docs
 [Rust]: https://www.rust-lang.org/tools/install
 [pnpm]: https://pnpm.io
+
+## Contribution guidelines
+
+These guidelines apply to all Modrinth projects. Following them will help your contributions get reviewed and merged smoothly.
+
+### Keep pull requests small and focused
+
+We strongly encourage small, focused pull requests over large, sweeping changes. Bug fixes, QOL improvements, and other incremental contributions are much easier to review and more likely to be merged quickly. If you're looking for something to work on, check out the [GitHub issues](https://github.com/modrinth/code/issues) tab for open tasks and known bugs.
+
+### Pull request descriptions
+
+Every PR should include a clear description of what it does. Briefly explain what was added, updated, or fixed, and provide any relevant context for reviewers. If your PR fixes or relates to an existing issue, reference the issue number in the description (e.g., `Fixes #1234`) as this helps maintain traceability and automatically closes issues when the PR is merged.
+
+### Pull request titles
+
+Make sure the title starts with a semantic prefix:
+
+- **feat**: A new feature
+- **fix**: A bug fix
+- **devex**: Improves developer experience
+- **refactor**: A code change that neither fixes a bug nor adds a feature
+- **style**: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
+- **docs**: Documentation only changes
+- **chore**: Other changes that don't modify src or test files
+- **revert**: Reverts a previous commit
+- **perf**: A code change that improves performance
+- **test**: Adding missing tests or correcting existing tests
+- **build**: Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm)
+- **ci**: Changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs)
+
+## Things to keep in mind
+
+Here are some tips and reminders to help you in your contribution.
+
+### Consult people on Discord
+
+There are a number of reasons to want to consult with people on our [Discord] before making a pull request. For example, if you're not sure whether something is a good idea or not, if you're not sure how to implement something, or if you can't get something working, these would all be good opportunities to create a thread in the `#development` forum channel.
+
+If you intend to work on new features, to make significant codebase changes, or to make UI/design changes, please open a discussion thread first to ensure your work is put to its best use.
+
+### Don't get discouraged
+
+At times, pull requests may be rejected or left unmerged for a variation of reasons. Don't take it personally, and don't get discouraged! Sometimes a contribution just isn't the right fit for the time, or it might have just been lost in the mess of other things to do. Remember, the core Modrinth team are often busy, whether it be on a specific project/task or on external factors such as offline responsibilities. It all falls back to the same thing: don't get discouraged!
+
+### Code isn't the only way to contribute
+
+You don't need to know how to program to contribute to Modrinth. Quality assurance, supporting the community, coming up with feature ideas, and making sure your voice is heard in public decisions are all great ways to contribute to Modrinth. If you find bugs, reporting them on the appropriate issue tracker is your responsibility; however, remember that potential security breaches and exploits must instead be reported in accordance with our [security policy](https://modrinth.com/legal/security).
diff --git a/apps/docs/src/content/docs/contributing/knossos.md b/apps/docs/src/content/docs/contributing/knossos.md
@@ -1,35 +1,32 @@
 ---
-title: Knossos (Frontend)
+title: Modrinth Website
 description: Guide for contributing to Modrinth's frontend
+sidebar:
+  order: 2
 ---
 
-This project is part of our [monorepo](https://github.com/modrinth/code). You can find it in the `apps/frontend` directory.
+The [Modrinth Website], codename Knossos, is a Nuxt.js frontend. You will need to install [pnpm] and run the standard commands:
 
-[knossos] is the Nuxt.js frontend. You will need to install [pnpm] and run the standard commands:
+## Setup
 
-```bash
-pnpm install
-pnpm run web:dev
-```
+### 1. Install prerequisites
 
-Once that's done, you'll be serving knossos on `localhost:3000` with hot reloading. You can replace the `dev` in `pnpm run dev` with `build` to build for a production server and `start` to start the server. You can also use `pnpm run lint` to find any eslint problems, and `pnpm run fix` to try automatically fixing those problems.
+- Install the package manager [pnpm](https://pnpm.io/)
 
-<details>
-<summary>.env variables & command line options</summary>
+### 2. Install dependencies & set up .env
 
-#### Basic configuration
+- Clone [`https://github.com/modrinth/code`](https://github.com/modrinth/code) and run `pnpm install` in the workspace root folder.
+- In `apps/frontend` you should be able to see `.env.prod`, `.env.staging` — for basic work, it's recommended to use `.env.prod`. Copy the relevant file into a new `.env` file within the `apps/frontend` folder.
 
-`SITE_URL`: The URL of the site (used for auth redirects). Default: `http://localhost:3000`
-`BASE_URL`: The base URL for the API. Default: `https://staging-api.modrinth.com/v2/`
-`BROWSER_BASE_URL`: The base URL for the API used in the browser. Default: `https://staging-api.modrinth.com/v2/`
+### 3. Run the frontend
 
-</details>
+- Run `pnpm web:dev` in the workspace root folder. Once that's done, you'll be serving the website on `localhost:3000` with hot reloading.
 
-#### Ready to open a PR?
+## Ready to open a PR?
 
 If you're prepared to contribute by submitting a pull request, ensure you have met the following criteria:
 
-- `pnpm run fix` has been run.
+- `pnpm prepr:frontend` has been run.
 
-[knossos]: https://github.com/modrinth/code/tree/main/apps/frontend
+[Modrinth website]: https://github.com/modrinth/code/tree/main/apps/frontend
 [pnpm]: https://pnpm.io
diff --git a/apps/docs/src/content/docs/contributing/labrinth.md b/apps/docs/src/content/docs/contributing/labrinth.md
@@ -1,6 +1,8 @@
 ---
 title: Labrinth (API)
 description: Guide for contributing to Modrinth's backend
+sidebar:
+  order: 4
 ---
 
 This project is part of our [monorepo](https://github.com/modrinth/code). You can find it in the `apps/labrinth` directory. The instructions below assume that you have switched your working directory to the `apps/labrinth` subdirectory.
@@ -89,7 +91,7 @@ The OAuth configuration options are fairly self-explanatory. For help setting up
 
 </details>
 
-#### Ready to open a PR?
+## Ready to open a PR?
 
 If you're prepared to contribute by submitting a pull request, ensure you have met the following criteria:
 

diff --git a/apps/docs/src/content/docs/contributing/minotaur.md b/apps/docs/src/content/docs/contributing/minotaur.md
@@ -1,6 +1,8 @@
 ---
 title: Minotaur (Gradle plugin)
 description: Guide for contributing to Modrinth's gradle plugin
+sidebar:
+  order: 5
 ---
 
 [Minotaur][minotaur] is the Gradle plugin used to automatically publish artifacts to Modrinth. To run your copy of the plugin in a project, publish it to your local Maven with `./gradlew publishToMavenLocal` and add `mavenLocal()` to your buildscript.

diff --git a/apps/docs/src/content/docs/contributing/theseus.md b/apps/docs/src/content/docs/contributing/theseus.md
@@ -1,22 +1,32 @@
 ---
-title: Theseus (Modrinth App)
+title: Modrinth App
 description: Guide for contributing to Modrinth's desktop app
+sidebar:
+  order: 3
 ---
 
-This project is part of our [monorepo](https://github.com/modrinth/code). You can find it in the `apps/app` directory.
+The [Modrinth App], codename Theseus, is the Tauri-based launcher that lets users conveniently play any mod or modpack on Modrinth. It uses the Rust-based Tauri as the backend and Vue.js as the frontend.
 
-[theseus] is the Tauri-based launcher that lets users conveniently play any mod or modpack on Modrinth. It uses the Rust-based Tauri as the backend and Vue.js as the frontend. To get started, install [pnpm], [Rust], and the [Tauri prerequisites](https://v2.tauri.app/start/prerequisites/) for your system. Then, run the following commands:
+## Setup
 
-```bash
-pnpm install
-pnpm run app:dev
-```
+### 1. Install prerequisites
 
-Once the commands finish, you'll be viewing a Tauri window with Nuxt.js hot reloading.
+- [pnpm](https://pnpm.io/)
+- [Rust](https://www.rust-lang.org/tools/install)
+- [Tauri prerequisites](https://v2.tauri.app/start/prerequisites/)
 
-You can use `pnpm run lint` to find any eslint problems, and `pnpm run fix` to try automatically fixing those problems.
+### 2. Install dependencies & set up .env
 
-### Theseus Architecture
+- Clone [`https://github.com/modrinth/code`](https://github.com/modrinth/code) and run `pnpm install` in the workspace root folder.
+- In `packages/app-lib` you should be able to see `.env.prod`, `.env.staging` — for basic app work, it's recommended to use `.env.prod`. Copy the relevant file into a new `.env` file within the `packages/app-lib` folder.
+
+### 3. Run the app
+
+- Run `pnpm app:dev` in the workspace root folder.
+- If you encounter an "Unable to initialise GTK" error on Linux, try running `pnpm run dev` within the `apps/app` folder rather than the workspace root command. If this doesn't work, use a VM with Windows and repeat these steps.
+- If you get issues with being unable to find a display, and you're running the dev env inside a container (e.g. an Arch dev container on a non-Arch host), run `xhost +local:` to allow it to bind to an X11/Xwayland socket.
+
+## Theseus Architecture
 
 Theseus is split up into three parts:
 
@@ -30,15 +40,15 @@ When running SQLX commands, be sure to set the `DATABASE_URL` environment variab
 
 You can edit the app's data directory using the `THESEUS_CONFIG_DIR` environment variable.
 
-#### Ready to open a PR?
+## Ready to open a PR?
 
 If you're prepared to contribute by submitting a pull request, ensure you have met the following criteria:
 
-- Run `pnpm run fix` to address any fixable issues automatically.
+- Run `pnpm prepr:frontend` to address any fixable issues automatically.
 - Run `cargo fmt` to format Rust-related code.
 - Run `cargo clippy` to validate Rust-related code.
 - Run `cargo sqlx prepare --package theseus` if you've changed any SQL code to validate statements.
 
-[theseus]: https://github.com/modrinth/code/tree/main/apps/app
+[Modrinth App]: https://github.com/modrinth/code/tree/main/apps/app
 [Rust]: https://www.rust-lang.org/tools/install
 [pnpm]: https://pnpm.io