up/docs/contributing/index.md

title
Contributing

Contributing to Tree of Ascension Docs

Welcome! This guide will get you from zero to making your first edit — even if you've never used git before.

🔒 Registration is currently closed. 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 🌱 → 🌳

Once you have access, read on below.

---

🛠 How it works

What	Details
Site host	Forgejo — a friendly, self-hosted git platform
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

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. This keeps the main site safe while you work.

• 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

• git — the version control tool
• Tolaria — a friendly Markdown editor with git support

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

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.