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
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:

Go to bali.krystl.org/aja/up
Find the "Download" or "⋯" menu near the top of the file list
Choose "Download ZIP"
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¶

Build the site and upload the site/ folder to your hosting provider
Point your domain's DNS to your host (your provider will have instructions)
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.