Skip to content

Improve the doc contribution workflow #772

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.

Sign up for GitHub

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

Merged
Juminstock merged 3 commits into from
Dec 1, 2025
Merged

Improve the doc contribution workflow #772

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
43a2661
Update: Improve the contribution workflow
Juminstock Dec 1, 2025
3dbafc5
Updated internal members terms to Organization members
Gunit2481 Dec 1, 2025
bb1ab13
Merge main into feat-juminstock/update-readme
Juminstock Dec 1, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
248 changes: 185 additions & 63 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,113 +4,235 @@ Welcome to Astar Documentation GitHub Repository! 🗂️

This website is built using [**Docusaurus**](https://docusaurus.io/), a modern static website generator.

## How to contribute using a local instance of the Docusaurus engine
## Prerequisites

### Method 1:

Make sure `git`, `node` and `yarn` exist as commands in your terminal or code editors like **Visual Studio Code**.
Before you begin, make sure the following tools are installed on your system:

* [**Git**](https://git-scm.com/downloads)
* [**Node.js**](https://nodejs.org/en)
* [**Yarn**](https://yarnpkg.com/)
* [**Node.js**](https://nodejs.org/en) - version 22.17.0 or greater
* [**Yarn**](https://yarnpkg.com/) - version 4.9.2 or greater

You can verify your installations by running:
```bash
git --version
node --version
yarn --version
```

## How to Contribute

Choose your contribution path based on whether you are a member of the Astar Collective Github Organization or an external contributor:

**🔖 NOTE:** Use a Node.js version equal to or greater than `22.17.0` and a Yarn version equal to or greater than `4.9.2`.
<details>
<summary><b>Organization Contributors (Astar Collective)</b></summary>

**Git/Github:** understand what the following commands do:
If you are part of the Astar organization on GitHub and have write access to the repository, follow these steps:

* Managing branches:
### Step 1: Set Up Your Local Environment

Clone the repository and navigate to it:
```bash
git clone https://github.com/astarnetwork/astar-docs
cd astar-docs
```

Ensure you are on the main branch and have the latest version:
```bash
git checkout main
git checkout -b feat/your-new-branch
git pull
```

### Step 2: Create a New Branch

Create a new feature branch for your changes:
```bash
git checkout -b feat/your-feature-name
```
* Commits:

Install dependencies using yarn:
```bash
yarn install
```

git add .
git commit -m "Your-message-here"
**💡 TIP:** Use descriptive branch names like `feat/update-tokenomics` or `fix/broken-links`.

git push -u origin feat/your-new-branch
### Step 3: Make Your Changes

Start the local development server to preview your changes in real-time:
```bash
yarn start
```

* Create a PR on GitHub and be as detailed as possible about your changes.
This command will launch a local server (typically at `http://localhost:3000`) where you can see your changes as you edit the documentation.

**💡 TIP:** Maybe stashing `git stash` and `git stash pop` will be your best friends.
Make your edits to the documentation files. You should be familiar with:

* **Markdown basics:** titles, subtitles, lists, hyperlinks, code blocks
* **File structure:** understanding where different documentation sections are located

### Step 4: Test Your Changes

Before committing, ensure the documentation builds without errors:
```bash
yarn build
```

- Markdown basics:
- titles, subtitles
- lists
- hyperlinks
If the build completes successfully, you are ready to commit your changes.

### Method 2:
### Step 5: Commit and Push Your Changes

Make sure `node` and `yarn` exist as commands in your terminal or VS Code and [**Github Desktop**](https://desktop.github.com/download/) is installed. All the `git` operations described below can also be found within the menu of the desktop application, and common operations are clearly visible on launch.
Add your changes and create a commit with a descriptive message:
```bash
git add .
git commit -m "Description of your changes"
```

**New document / Modify existing document → Submit a PR ✅**

* Get latest version of docs locally
Push your branch to GitHub:
```bash
git push -u origin feat/your-feature-name
```

* Clone repo → `git clone https://github.com/astarnetwork/astar-docs`
* Move inside the repository → `cd astar-docs`
* Make sure you’re on the main branch → `git checkout main`
* Pull the latest version of the docs → `git pull`
* Create a new branch → `git checkout -b feat/new-feature-name-here`
* Install dependencies by running → `yarn` or `yarn install`
**💡 TIP:** If you need to temporarily save your work without committing, use `git stash` and later restore with `git stash pop`.

* Create/update the docs as you please
### Step 6: Create a Pull Request

* Start the local development server by running → `yarn start`
* Add new page/tweaks/etc
* When you’re happy with it, ensure `yarn build` runs without errors
1. Go to https://github.com/astarnetwork/astar-docs
2. Create a new Pull Request from your feature branch to `main`
3. Provide a detailed description of your changes
4. Once the PR is created, CI/CD will automatically generate a unique staging link for review
5. You can monitor the build progress in the Actions tab on GitHub
6. Wait for feedback from the team

* PR and staging environment
</details>

* Commit your changes and push the new branch up to Github
```bash
<details>
<summary><b>External Contributors (Community Members)</b></summary>

git add .
git commit -m "Your-message-here"

git push -u origin feat/your-new-branch
If you are not part of the Astar organization on GitHub, you will need to fork the repository first before making contributions.

```
### Step 1: Fork the Repository

* Create a new PR on Github → https://github.com/astarnetwork/astar-docs
1. Go to https://github.com/astarnetwork/astar-docs
2. Click the **Fork** button in the top-right corner
3. This creates a copy of the repository under your GitHub account

* Once PR is up, **CI/CD** will automatically build you a unique staging link.
* You can view the progress of this on the Actions tab on Github
* Wait for feedback from the team
### Step 2: Set Up Your Local Environment

## Working with images
Clone your forked repository (replace `YOUR-USERNAME` with your GitHub username):
```bash
git clone https://github.com/YOUR-USERNAME/astar-docs
cd astar-docs
```

Please import and use the `<Figure/>` tag instead of `![image]` as this enables smoother translation of docs to other languages (automatic reference to original images, no need to copy images to translated subfolders) and automatically applies some styling such as line breaks.

**🧑🏻‍💻 Example as seen [here](https://github.com/AstarNetwork/astar-docs/blob/d530139ca7a5ab034a783981d313542e02fdfb54/docs/about/token-economics/inflationary-model.md).**

**Top of file:**
Add the original repository as an upstream remote to keep your fork synchronized:
```bash
git remote add upstream https://github.com/astarnetwork/astar-docs
```

import Figure from "/src/components/figure"
### Step 3: Create a New Branch

Ensure you have the latest changes from the original repository:
```bash
git checkout main
git pull upstream main
```

**Within the file:**
Create a new feature branch for your changes:
```bash
<Figure caption="Tokenomics Model" src={require('/docs/about/token-economics/img/tokenomics_1.png').default } width="100%" />
git checkout -b feat/your-feature-name
```

Install dependencies using yarn:
```bash
yarn install
```

* Please use absolute path to image (e.g. `/docs/about/token-economics/img/tokenomics_1.png` instead of `img/tokenomics_1.png`).
### Step 4: Make Your Changes

## Deploy to production
Start the local development server to preview your changes in real-time:
```bash
yarn start
```

When a PR is ready for merge, click the button at the bottom saying **Merge and Close** and then **Confirm**.
This command will launch a local server (typically at `http://localhost:3000`) where you can see your changes as you edit the documentation.

Make your edits to the documentation files. You should be familiar with:

* **Markdown basics:** titles, subtitles, lists, hyperlinks, code blocks
* **File structure:** understanding where different documentation sections are located

### Step 5: Test Your Changes

Before committing, ensure the documentation builds without errors:
```bash
yarn build
```

If the build completes successfully, you are ready to commit your changes.

### Step 6: Commit and Push Your Changes

Add your changes and create a commit with a descriptive message:
```bash
git add .
git commit -m "Description of your changes"
```

Push your branch to your forked repository:
```bash
git push -u origin feat/your-feature-name
```

### Step 7: Create a Pull Request

1. Go to your forked repository on GitHub (https://github.com/YOUR-USERNAME/astar-docs)
2. Click **Compare & pull request**
3. Ensure the base repository is `astarnetwork/astar-docs` and the base branch is `main`
4. Provide a detailed description of your changes
5. Submit the Pull Request
6. Once the PR is created, CI/CD will automatically generate a unique staging link for review
7. You can monitor the build progress in the Actions tab on GitHub
8. Wait for feedback from the Astar team

### Step 8: Keep Your Fork Updated

To keep your fork synchronized with the original repository:
```bash
git checkout main
git pull upstream main
git push origin main
```

</details>

## Working with Images

Please import and use the `<Figure/>` tag instead of `![image]` as this enables smoother translation of docs to other languages (automatic reference to original images, no need to copy images to translated subfolders) and automatically applies some styling such as line breaks.

**🧑🏻‍💻 Example as seen [here](https://github.com/AstarNetwork/astar-docs/blob/d530139ca7a5ab034a783981d313542e02fdfb54/docs/about/token-economics/inflationary-model.md).**

**Top of file:**
```javascript
import Figure from "/src/components/figure"
```

**Within the file:**
```javascript
<Figure caption="Tokenomics Model" src={require('/docs/about/token-economics/img/tokenomics_1.png').default } width="100%" />
```

**Important:** Please use absolute path to image (e.g. `/docs/about/token-economics/img/tokenomics_1.png` instead of `img/tokenomics_1.png`).

After a few minutes you should see your changes updated on the production site at [**Astar Network Documentation**](https://docs.astar.network).

## HELP! Something is broken 🔍

Likely, a broken build got pushed to `main` somehow. Remove the commit from `main` and force push to `main`, reopen PR in a new PR.
Likely, a broken build got pushed to `main` somehow. Remove the commit from `main` and force push to `main`, reopen PR in a new PR.



## Deploy to Production

**For Organization Contributors Only:**

When a PR is ready for merge, click the button at the bottom saying **Merge and Close** and then **Confirm**.

After a few minutes you should see your changes updated on the production site at [**Astar Network Documentation**](https://docs.astar.network).