Lilka Catalog

Українська версія / Ukrainian version

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)
  • Download link for packaged ZIP (manifest.yml + entry/mod/additional files)
  • Source repository links
  • Icons and screenshots
• Localization: English and Ukrainian (uk, en) content with a language switcher in the site header. Default/fallback language is Ukrainian (uk).

File Structure

apps/                   # Source apps directory
├── [app-name].app/
│   ├── manifest.yml      # App manifest
│   ├── DESCRIPTION.uk.md # Full description (Ukrainian)
│   ├── DESCRIPTION.en.md # Full description (English)
│   ├── 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
│       ├── package.zip       # Packaged app files + manifest
│       └── static/           # Downloaded assets
│           ├── icon.png
│           ├── screenshot*.png
│           └── execution_file
└── mods/
    ├── index_0.json    # Mods pagination index
    └── [mod-name].case/
        ├── index.json  # Mod manifest
      ├── package.zip # Packaged mod files + 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:

manifest.yml Reference

The build script (build.py) validates every manifest. If a required field is missing, the app/mod is skipped during the build. Missing optional fields only produce warnings in build/warnings.json.

Required fields

Field	Applies to	Description
name	apps & mods	Item name. Plain string or localized map (uk/en)
keira_version	apps only	Minimum Keira firmware version the app requires
short_description	apps & mods	Brief description. Plain string or localized map
author	apps & mods	Author name
sources	apps & mods	Source repository. Must contain type and location.origin

sources:
  type: git
  location:
    origin: https://github.com/yourusername/yourrepo.git

Optional fields

Field	Applies to	Description
description	apps & mods	Full description. Inline text, localized map, or "@DESCRIPTION.md" file reference
changelog	apps & mods	Version history. Inline text, localized map, or "@CHANGELOG.md" file reference
icon	apps & mods	Icon file (local path or URL). Compressed to max 512x512; a 64x64 RGB565 icon_min is generated for the device
screenshots	apps & mods	List of images (local paths or URLs). Compressed to max 1920x1080
entryfile	apps only	The app's executable file, with type (lua, archive, or binary) and location.origin. executionfile is accepted as a legacy alias
files	apps & mods	List of additional files to bundle, each with location.origin
modfiles	mods only	List of mod files, each with a name and location.origin

Note: the declared entryfile.type must match the file extension (.lua → lua; .zip/.tar/.tar.gz/.tgz → archive; .bin → binary), otherwise the build emits a type_mismatch warning.

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
icon: icon.png
screenshots:
  - screenshot1.png
  - screenshot2.png
sources:
  type: git
  location:
    origin: https://github.com/yourusername/yourrepo.git
entryfile:
  type: lua  # lua, archive or binary — must match the file extension
  location:
    origin: https://url-to-your-executable-file

3. Add the referenced 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 (no keira_version needed), but use modfiles instead of entryfile:

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

Localization (English & Ukrainian)

The catalog supports two content languages: Ukrainian (uk, default/fallback) and English (en). Localizable manifest fields are name, short_description, description, and changelog.

There are two ways to provide localized content:

1. Localized markdown files for long-form fields (description, changelog). Reference the base file in the manifest and add language-suffixed siblings:

   description: "@DESCRIPTION.md"   # build resolves DESCRIPTION.uk.md / DESCRIPTION.en.md
   changelog: "@CHANGELOG.md"       # build resolves CHANGELOG.uk.md / CHANGELOG.en.md

   Then create:

   • DESCRIPTION.uk.md — Ukrainian
   • DESCRIPTION.en.md — English

   If only a non-localized DESCRIPTION.md exists, it is used as the Ukrainian (default-language) content, so existing single-language apps keep working.

2. Inline localized values for short fields (name, short_description):

   name:
     uk: Таймер
     en: Timer
   short_description:
     uk: Простий таймер зворотного відліку зі звуковим сповіщенням
     en: A simple countdown timer with a sound notification

   A plain string is still accepted and is treated as the default language:

   name: Таймер

The build writes a localization object and a languages list into each index.json / index_short.json. The site's language switcher uses this data and falls back to Ukrainian (then any available language) when a translation is missing.

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