Steel Docs

This is the main repository for the SteelMC documentation, made using Astro Starlight.

---

📖 Table of Contents

• How to contribute
  • Identify
  • Fork
  • Install
  • Commit
  • Internationalization
• How to use
• Project structure

---

Contribute

Note

All the following steps require you to have a version of git and bun running on your system.

Starlight looks for .md or .mdx files in the src/content/docs/ directory. Each file is exposed as a route based on its file name. Images can be added to src/assets/ and embedded in Markdown with a relative link. Static assets, like favicons, can be placed in the public/ directory.

Identify

... a feature you'd like to add or an issue to work on. You should always create an issue or a draft-pr describing what you want, before considering adding a major feature.

Fork

... the master branch of this repository, so you can prepare your changes locally. Clone it to your system by running the command

git clone https://github.com/{your-name}/SteelDocs

in your directory of choice. Don't forget to set this repository as its upstream by running the following command in said directory;

git remote add upstream https://github.com/Steel-Foundation/SteelDocs.git

To test if it has succeeded, enter:

git remote -v

Which should yield the following.

origin   https://github.com/{your-name}/SteelDocs.git (fetch)
origin   https://github.com/{your-name}/SteelDocs.git (push)
upstream https://github.com/Steel-Foundation/SteelDocs.git (fetch)
upstream https://github.com/Steel-Foundation/SteelDocs.git (push)

Now set-up a new feature branch by running

git checkout -b feat-{feature-name}

from the master branch.

Installation

To install the dependencies, run the following command inside the root folder of the project:

bun install

Commit

... your changes to your fork by using the following commands in its directory:

git add .
git commit -m "{your-message}"
git push origin {your-branch}

Then you may open a pull-request by comparing the changes on the github website.

Note

This project strictly enforces the use of the conventional commits standard in the commit messages. Also please remember to strictly use relative paths!

Internationalization

Starlight uses a particular folder structure to automatically fetch and correctly link translated markdown files. For this reason, if you want to add a new language, you should create a new folder with the correct international prefix in the docs folder, where both the german and spanish translations already reside. The english originals are also stored in the docs folder, but don't require another wrapper folder, such that it can be used as fallback. Otherwise, the only things you should look out for are:

Articles are written in .md (markdown) files and contain a front-matter like this:

---
title: Feature Flags
description: Complete reference of all compile-time feature flags in SteelMC
sidebar:
  order: 1
---

Here, useful information about the article is stored.

Furthermore, side-bar slugs are translated by adding an entry to the translations array inside the sidebar object, which can be found inside astro.config.mjs, like this:

label: 'Getting started',
translations: {
    es: 'Primeros pasos',
    de: 'Erste Schritte'
},

For further guidance, feel free to consult the documentation for i18n internationalization from Astro.

How to use

Inside the project folder run bun dev for hosting it locally. Keep in mind that this will sometimes mask errors, which will only be exprimated when hosted somewhere like gh pages. The rest should be handled by the deploy workflow.

Project structure

SteelDocs
├─ astro.config.ts
├─ bun.lock
├─ package.json
├─ public
│  └─ favicon.svg
├─ README.md
├─ src
│  ├─ assets
│  │  └─ houston.webp
│  ├─ content
│  │  └─ docs
│  │     ├─ guides
│  │     │  └─ example.md
│  │     ├─ index.mdx
│  │     └─ reference
│  │        └─ example.md
│  └─ content.config.ts
└─ tsconfig.json