Skip to content

# Contributing to Tree of Ascension Docs

Welcome! This guide will get you from zero to making your first edit or new post contribution to Tree of Ascension Docs.

> 🔒 Registration is currently closed. Self-registration of new contributor accounts are not available at this moment. If you'd like to get involved, solve the puzzle below to reveal the contact email and request access.

## 🔐 Request access

🌱 Click each leaf in order to reveal the contact email:

Click them from smallest to largest 🌱 → 🌳

Single article

If you just want to contriubute a simple edit or a single article you can send it to the above address and we'll handle adding it to the site for you.

Once you have access, read on below.

## 🛠 How it works

What | Details
--- | ---
Code and file hosting | Forgejo — a friendly, self-hosted git (version control) platform that manages changes and files between many users. Git is a distributed open source tool that lets you work on a folder of files and handles the cases where two users have edited the same file (called merge conflicts).
Repo | bali.krystl.org/aja/up
Built with | Zensical — turns Markdown files into a beautiful docs site
Local editor | Tolaria — a simple desktop app for editing Markdown with git built in

## ✏️ Making your first edit directly on Forgejo (easiest as no local setup required)

Follow these steps. If you get stuck, the answer is usually just a few clicks away.

### Step 1 — Open the repo in Forgejo

Go to bali.krystl.org/aja/up and sign in with your account.

### Step 2 — Create your branch

Every edit lives on its own branch. A branch is a copy of the code that can be kept independent and later merged. This keeps the main site safe while you work and allows us to review and approve or comment on changes.

- Click the branch dropdown (near the top of the page, it probably says `main` or `master` )

- Type a short name for your branch — like `add-meditation-guide` or `fix-typo-daily-sadhana`

- Click "Create branch"

You're now on your own copy of the site. Any changes you make stay on this branch until you're ready to share them.

### Step 3 — Edit a file

- Browse to the file you want to edit (all content lives in the `docs/` folder)
- Click the pencil icon (✏️) in the toolbar above the file
- Make your changes using Markdown (see our Markdown quick reference)

- Scroll down and write a short commit message — something like `Add breathing exercise section`

- Click "Commit changes"

### Step 4 — Open a Pull Request

When your changes are ready:

- Go back to the repo homepage
- You'll see a banner: "You pushed to your branch — want to open a pull request?"
- Click "Compare & pull request"
- Add a title and a short description of what you changed
- Click "Create pull request"

A maintainer will review your changes and merge them into the main site. That's it! 🎉

## 💻 Editing locally (optional)

If you prefer to work on your own computer:

### You'll need

- Tolaria — a friendly Markdown editor with git support
- You can also use any text editor together with git — the version control tool

### Steps

    # 1. Clone the repo
    git clone https://bali.krystl.org/aja/up.git
    cd up

    # 2. Create your branch
    git checkout -b my-edit

    # 3. Open the folder in Tolaria and start editing

    # 4. When done, commit and push
    git add .
    git commit -m "Describe your changes"
    git push -u origin my-edit

    # At this point you'll be asked for your username and password.
    # You can also set up an SSH key which will mean you don't need to type these every time (you will need to email us your public key)

Then follow Step 4 above ("Open a Pull Request") to open your pull request on Forgejo.

## 🌱 Plant Your Own

Want to run your own version of this site? You can copy it and publish it under your own domain.

### Copy the repo

Option A — With git (recommended):

    git clone https://bali.krystl.org/aja/up.git my-own-site
    cd my-own-site

Option B — Download as ZIP:

1. Go to bali.krystl.org/aja/up
2. Find the "Download" or "⋯" menu near the top of the file list
3. Choose "Download ZIP"
4. Unzip it on your computer

### Set up Zensical

This site uses Zensical to build from Markdown. Install it and edit the config:

    # Install Zensical (Python 3.12+ required)
    pip install zensical

    # Or with uv (recommended):
    uv add --dev zensical

### Make it yours

Open `zensical.toml` and change:

    site_name = "Your Site Name"
    site_description = "What your site is about"
    site_url = "https://your-domain.com"
    site_author = "You"
    repo_url = "https://your-forgejo-instance/you/your-repo"

Replace `docs/assets/images/tree-ad-logo.svg` with your own logo, then build:

    zensical build --config-file zensical.toml

Your site appears in the `site/` folder — upload it to any static host (Netlify, Cloudflare Pages, a VPS, or keep it on Forgejo Pages).

### Use your own domain

1. Build the site and upload the `site/` folder to your hosting provider
2. Point your domain's DNS to your host (your provider will have instructions)
3. Update `site_url` in `zensical.toml` to match

That's it — you now have your own Zensical-powered knowledge garden.

Questions? Found a bug? Open an issue on the repo.

## Keep In Touch

Leave your WhatsApp or email to get updates on the journey.

## Comments