Lilka Catalog

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

A static website for browsing Lilka apps, wallpapers 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, wallpapers) 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

wallpapers/             # Source Lua wallpapers/screensavers (same layout as apps)
├── [wallpaper-name]/
│   └── manifest.yml

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 & wallpapers	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 & wallpapers	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 Wallpapers

Wallpapers are Lua screensavers, animated backgrounds and watchfaces.

1. Create a new directory in wallpapers/
2. Use the same manifest.yml structure as apps (keira_version is required), with a lua entryfile:

entryfile:
  type: lua
  location:
    origin: https://url-to-your-wallpaper.lua

3. Add required files and 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, wallpapers/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

Install the Python dependencies (Python 3.9+):

pip install -r requirements.txt

Run the build script to compile the complete static site:

./scripts/build.site.sh

This will:

1. Process all manifests in apps/, wallpapers/ 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