223 lines
9.7 KiB
Markdown
223 lines
9.7 KiB
Markdown
---
|
|
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 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
|
|
|
|
<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>
|
|
|
|
!!! info "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](https://forgejo.org) — 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](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 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](https://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](https://zensical.org/docs/authoring/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](https://tolaria.dev)** — a friendly Markdown editor with git support
|
|
- You can also use any text editor together with **[git](https://git-scm.com/downloads)** — the version control tool
|
|
|
|
### 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
|
|
|
|
# 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):**
|
|
|
|
```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.
|