Labyricorn Static Site publishing Engine (labyricorn-engine)

Labyricorn is a Git-driven, fully deterministic static website generator and publishing engine. It uses a Gitea instance as the single source of truth, compiles content (Markdown files) and discussions (Gitea Issues/Comments), and serves them statically via Nginx.

No CMS database. No runtime backend engines. No Docker overhead. Built to run natively in lightweight Linux Containers (LXC).

---

🛠️ System Architecture

Gitea (git.labyricorn.com)
        ↓
Python Sync Engine (running via cron every 5 minutes)
        ↓
Static Filesystem Output (/var/www/labyricorn/)
        ↓
Nginx Web Server (serving static files with Clean URLs)

---

📂 Project Structure

/root/labyricorn/           # Main Git workspace
├── gitea_client.py         # Gitea API authentication, repository scanner & archive downloader
├── metadata.py             # Parser for repository-level .labyricorn/site.yml configurations
├── renderer.py             # Markdown-to-HTML converter (includes TOC, code highlight, and asset mapping)
├── writer.py               # Handles filesystem writes, media asset copies, and index.json cataloging
├── sync.py                 # Core orchestrator script
├── install.sh              # Bash installer for system deployment
├── nginx-labyricorn.conf   # Nginx server configuration (with clean URLs support)
├── setup_real_gitea.py     # Script to populate Gitea with sample test content
├── .gitignore              # Files excluded from Git tracking
└── templates/              # Jinja2 HTML layouts
    ├── base.html           # Master layout with light/dark theme switch and radial glow styling
    ├── index.html          # Homepage with hero banner, featured posts, and latest articles
    ├── list.html           # Catalog listing with real-time text-filtering search in JS
    ├── article.html        # Layout for articles (includes table of contents and comments timeline)
    ├── project.html        # Layout for projects (includes repository stats for forks/stars/issues)
    └── doc.html            # Layout for documentation guides

---

🚀 Installation & Deployment

Deploying the sync engine to your local LXC environment is simple:

1. Clone or pull the repository into your local environment.
2. Review your configuration or let the installer generate /etc/labyricorn/sync.yml with your Gitea token.
3. Run the installer script:

   sudo chmod +x install.sh
   sudo ./install.sh

The script will:

• Copy files to their permanent runtime directory: /opt/labyricorn/.
• Create a configuration file at /etc/labyricorn/sync.yml.
• Set up a system cron job in /etc/cron.d/labyricorn-sync to sync every 5 minutes.
• Copy and activate the Nginx server configuration.

---

📝 How to Publish Content

To publish an article, project, or documentation guide from Gitea:

1. Create a Repository

Create a repository on Gitea (e.g. my-awesome-project).

2. Configure Site Settings

Create a configuration file in the repository at .labyricorn/site.yml:

enabled: true
type: project              # content | project
visibility: featured       # hidden | listed | featured
section: projects          # articles | projects | docs
title: "My Awesome Project"
description: "A summary of what this project does."
tags:
  - python
  - automation
author: Admin

3. Add Markdown Content

Write your content in a README.md at the root of the repository. You can reference local images (e.g., images/diagram.png), which will be extracted and served automatically.

4. Discussions & Comments

Open issues inside the repository. The engine fetches issues and comments during sync runs and embeds them at the bottom of the page as a read-only discussion thread.

---

⚙️ Manual Synchronization

To trigger an immediate rebuild of the static site:

python3 /opt/labyricorn/sync.py --config /etc/labyricorn/sync.yml