Lilka Catalog

A static website for browsing Lilka apps and mods.

Features

• Detailed Modal Views: Click any item to see full details including:
  • Description and changelog (markdown formatted)
  • Author information
  • Download links for execution files (apps) or mod files (mods)
  • Source repository links
  • Icons and screenshots

File Structure

apps/                   # Source apps directory
├── [app-name].app/
│   ├── manifest.yml    # App manifest
│   ├── DESCRIPTION.md  # Full description
│   ├── CHANGELOG.md    # Version history
│   ├── icon.png        # App icon
│   └── screenshot*.png # Screenshots

mods/                   # Source mods directory
├── [mod-name].case/
│   ├── manifest.yml    # Mod manifest
│   ├── DESCRIPTION.md
│   ├── CHANGELOG.md
│   └── icon.png

site/                   # Static site source
├── index.html          # Main HTML page
├── styles.css          # All styling
└── script.js           # JavaScript application logic

build/                  # Generated by build.py
├── index.html          # Copied from site/
├── styles.css          # Copied from site/
├── script.js           # Copied from site/
├── warnings.json       # Build warnings
├── apps/
│   ├── index_0.json    # Apps pagination index
│   └── [app-name].app/
│       ├── index.json        # App manifest
│       ├── index_short.json  # Short manifest
│       └── static/           # Downloaded assets
│           ├── icon.png
│           ├── screenshot*.png
│           └── execution_file
└── mods/
    ├── index_0.json    # Mods pagination index
    └── [mod-name].case/
        ├── index.json  # Mod manifest
        └── static/     # Downloaded assets

scripts/
├── build.site.sh       # Build script to compile everything
└── generate_test_apps.py  # Generate test data

.github/workflows/
└── deploy-pages.yml    # GitHub Actions auto-deploy

build.py                # Main build script

How to Add Your App or Mod

To contribute your app or mod to the Lilka repository:

For Apps

1. Create a new directory in apps/ named yourapp.app
2. Create a manifest.yml file with the following structure:

name: Your App Name
keira_version: 1.0.0
short_description: Brief description
description: "@DESCRIPTION.md"  # Or inline text
changelog: "@CHANGELOG.md"      # Or inline text
author: Your Name
license: MIT
icon: icon.png
screenshots:
  - screenshot1.png
  - screenshot2.png
sources:
  type: git
  location:
    origin: https://github.com/yourusername/yourrepo.git
executionfile:
  type: lua  # or other type
  location:
    origin: https://url-to-your-executable-file

3. Add required files:

   • DESCRIPTION.md - Full description (if using @DESCRIPTION.md)
   • CHANGELOG.md - Version history (if using @CHANGELOG.md)
   • icon.png - App icon (will be compressed to 512x512)
   • Screenshots (will be compressed to max 1920x1080)

   Note: If your repository exists, you can reference files directly from it:

   icon: https://github.com/yourusername/yourrepo/raw/main/icon.png
   screenshots:
     - https://github.com/yourusername/yourrepo/raw/main/screenshot1.png
     - https://github.com/yourusername/yourrepo/raw/main/screenshot2.png
     - ./files/screenshot3.png

4. Submit a Pull Request

For Mods

1. Create a new directory in mods/ named yourmod.case
2. Create a manifest.yml file similar to apps, but use modfiles instead of executionfile:

modfiles:
  - name: File 1
    location:
      origin: https://url-to-file1
  - name: File 2
    location:
      origin: https://url-to-file2
  - name: File 3
    location:
      origin: ./files/path-to-file3

3. Add required files (or use URLs from your repository) and submit a Pull Request

Validation

The build system will automatically validate your submission:

• Critical checks (will skip if failed): Repository exists, execution/mod files accessible
• Non-critical warnings: Missing screenshots, missing icon (will still build with warnings)
• Check build/warnings.json for any issues after building

Run python build.py --build locally to test before submitting.

How It Works

1. Index Files: The site loads apps/index_0.json or mods/index_0.json based on the selected tab
2. Pagination: Each index file contains:
   • Current page number
   • Total pages available
   • List of manifest names for that page
3. Manifest Loading: For each manifest name, the site fetches [type]/[name]/index.json
4. Static Assets: Icons and files are loaded from [type]/[name]/static/

Usage

Local Development

Simply open index.html in a web browser. However, due to CORS restrictions, you'll need a local server:

# Using Python 3
cd build
python3 -m http.server 8000

Then visit: http://localhost:8000

GitHub Pages Deployment (Automatic)

The repository includes a GitHub Actions workflow that automatically builds and deploys to GitHub Pages on every push to the main branch.

Setup Steps:

1. Enable GitHub Pages:

   • Go to your repository settings
   • Navigate to "Pages" section
   • Under "Build and deployment", set:
     • Source: GitHub Actions

2. Push to main branch:

   git add .
   git commit -m "Setup GitHub Pages deployment"
   git push origin main

3. Wait for deployment:

   • Go to the "Actions" tab in your repository
   • Watch the "Build and Deploy to GitHub Pages" workflow run
   • Once complete, your site will be live at: https://<username>.github.io/<repository-name>/

What the workflow does:

• Installs Python and dependencies (PyYAML, requests)
• Runs build.py --build to generate JSON files from manifests
• Copies static site files (HTML, CSS, JS) to build directory
• Deploys the build/ folder to GitHub Pages

Manual Deployment: You can also deploy manually by uploading the build/ directory to:

• Netlify
• Vercel
• AWS S3 + CloudFront
• Any web server

Building

Run the build script to compile the complete static site:

./scripts/build.site.sh

This will:

1. Process all manifests in apps/ and mods/ directories (via build.py)
2. Generate JSON index files with proper pagination
3. Download/copy static assets (icons, execution files, mod files)
4. Copy site files (HTML, CSS, JS) to build/ directory
5. Verify all required files are present

Manual Build

You can also build components separately:

# Build only JSON files from manifests
python3 build.py --build

# Then manually copy site files
cp site/{index.html,styles.css,script.js} build/

JSON Structure

Index File (index_0.json)

{
  "page": 0,
  "total_pages": 1,
  "manifests": [
    "app-name",
    "another-app"
  ]
}

Manifest File ([name]/index.json)

{
  "name": "App Name",
  "description": "Full description...",
  "short_description": "Brief description",
  "changelog": "Version history...",
  "author": "@username",
  "icon": "icon.png",
  "sources": "{'type': 'git', 'location': {...}}",
  "executionfile": "{'type': 'lua', 'location': 'main.lua'}"
}

License

MIT