up/docs/contributing/index.md

---
title: Contributing
icon: lucide/heart-handshake
---

# 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

<div class="captcha-game" style="background:linear-gradient(135deg,#f0f7f2,#e5f0e8);border-radius:16px;padding:1.5rem 1.8rem;margin:1.2rem 0 1.8rem;text-align:center;border:1px solid #c8dcd0;">
  <p style="margin:0 0 1rem;color:#3d6b52;font-weight:650;font-size:1.05rem;">🌱 Click each leaf in order to reveal the contact email:</p>
  <div id="leaf-container" style="display:flex;gap:0.8rem;justify-content:center;align-items:center;flex-wrap:wrap;"></div>
  <p id="captcha-hint" style="margin:0.9rem 0 0;font-size:0.85rem;color:#6b8b7a;">Click them from smallest to largest 🌱 → 🌳</p>
  <div id="captcha-result" style="display:none;margin-top:1rem;padding:0.8rem 1rem;background:white;border-radius:10px;font-size:1.05rem;border:1px dashed #92ad9e;"></div>
</div>
  <script>
    (function(){
      if(window._leafCaptchaDone)return;window._leafCaptchaDone=true;
      var leafTypes=[{e:'🌱'},{e:'🌿'},{e:'🪴'},{e:'🌳'}];
      // shuffle
      for(var i=leafTypes.length-1;i>0;i--){var j=Math.floor(Math.random()*(i+1));var t=leafTypes[i];leafTypes[i]=leafTypes[j];leafTypes[j]=t;}
      var container=document.getElementById('leaf-container');
      var correct=[]; // will hold positions of 🌱,🌿,🪴,🌳 in shuffled visual order
      leafTypes.forEach(function(l,pos){
        if(l.e==='🌱')correct[0]=pos;
        if(l.e==='🌿')correct[1]=pos;
        if(l.e==='🪴')correct[2]=pos;
        if(l.e==='🌳')correct[3]=pos;
        var s=document.createElement('span');
        s.textContent=l.e;
        s.id='leaf-'+pos;
        s.style.cssText='cursor:pointer;display:inline-flex;align-items:center;justify-content:center;width:56px;height:56px;border-radius:50%;background:#4a8262;color:white;font-size:1.4rem;transition:all 0.3s;user-select:none;';
              s.onclick=function(){captchaClick(pos);};
              container.appendChild(s);
      });
      var order=[],step=0;
      function resetAll(){
        order=[];step=0;
        for(var i=0;i<4;i++){var p=document.getElementById('leaf-'+i);if(p)p.style.background='#4a8262';}
      }
      window.captchaClick=function(i){
        if(order.indexOf(i)!==-1)return;
        order.push(i);
        var p=document.getElementById('leaf-'+i);if(p)p.style.background='#b9a5d7';
        if(correct[step]===i){step++;
          if(step===4){
            var r=document.getElementById('captcha-result');
            r.innerHTML='📧 <a href=\"mailto:tree.ad@use.startmail.com\">tree.ad@use.startmail.com</a>';
            r.style.display='block';
            var h=document.getElementById('captcha-hint');
            h.textContent='✨ You found it! Send an email to request access.';
          }
        }else{
          resetAll();
          document.getElementById('captcha-hint').textContent='Not quite — try again! Click smallest to largest 🌱 → 🌿 → 🪴 → 🌳';
        }
      };
    })();
    </script>

Once you have access, read on below.

---

## 🛠 How it works

| What             | Details                                                                                      |
| ---------------- | -------------------------------------------------------------------------------------------- |
| **Site host**    | [Forgejo](https://forgejo.org) — a friendly, self-hosted git platform                        |
| **Repo**         | [bali.krystl.org/aja/up](https://bali.krystl.org/aja/up)                                     |
| **Built with**   | [Zensical](https://zensical.org) — turns Markdown files into a beautiful docs site           |
| **Local editor** | [Tolaria](https://tolaria.dev) — 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](https://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](markdown.md))
- 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](https://git-scm.com/downloads)** — the version control tool
- **[Tolaria](https://tolaria.dev)** — a friendly Markdown editor with git support

### Steps

```bash
# 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):**

```bash
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](https://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](https://zensical.org) to build from Markdown. Install it and edit the config:

```bash
# 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:

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

```bash
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](https://bali.krystl.org/aja/up/issues)** on the repo.