> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lynxhub.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Extension configuration

> Configure package settings and metadata for extensions.

To publish and distribute your extension, you must place two registry files and an icon at the root of your repository's `metadata` branch. These files are `metadata.json`, `versioning.json`, and `icon.png`.

***

## metadata.json

The `metadata.json` file contains the primary identity and descriptive information for your extension.

### Structure

The file must follow this structure:

* `id` (string): The unique identifier of your extension. It must use lowercase alphanumeric characters and hyphens.
* `title` (string): The display name of your extension shown in the LynxHub registry.
* `description` (string): A short sentence describing what your extension does.
* `type` (string): Must be set to `"extension"`.

### Example

Here is an example `metadata.json` file:

```json theme={null}
{
  "$schema": "https://raw.githubusercontent.com/KindaBrazy/LynxHub-Statics/refs/heads/schema/plugins/metadata.schema.json",
  "id": "python-toolkit",
  "title": "Python Toolkit",
  "description": "Effortlessly manage your Python environments and dependencies.",
  "type": "extension"
}
```

***

## versioning.json

The `versioning.json` file tracks your release history, compatible engine ranges, supported operating systems, and version changelogs. LynxHub reads this file to resolve target versions and download updates.

### Structure

The file consists of two root arrays:

#### versions

An array of release version objects. Each version object contains:

* `version` (string): The semantic version of the release (e.g., `"1.0.0"`).
* `commit` (string): The exact Git commit hash of the release on your `main` branch.
* `engines` (object):
  * `extensionApi` (string): The semver compatibility range of the LynxHub extension API (e.g., `"^2.0.0"`).
* `stage` (string): The release distribution channel. Use `"public"`, `"early_access"`, or `"insider"`.
* `platforms` (array): The target operating systems. Supported values are `"win32"`, `"linux"`, and `"darwin"`.

#### changes

An array of change logs for each release version. Each changelog object contains:

* `version` (string): The semantic version this changelog applies to.
* `date` (string): The release date formatted as `YYYY-MM-DD`.
* `items` (array): A list of category objects containing change descriptions. Typical categories are `🚀 New Features`, `🛠️ Improvements`, and `🐛 Bug Fixes`.

### Example

Here is an example `versioning.json` file:

```json theme={null}
{
  "versions": [
    {
      "version": "1.0.0",
      "commit": "abcdef1234567890abcdef1234567890abcdef12",
      "engines": {
        "extensionApi": "^2.0.0"
      },
      "stage": "public",
      "platforms": ["win32", "linux", "darwin"]
    }
  ],
  "changes": [
    {
      "version": "1.0.0",
      "date": "2026-06-19",
      "items": [
        {
          "🚀 New Features": ["Initial release of the extension."]
        }
      ]
    }
  ]
}
```

***

## icon.png

The `icon.png` file is the display icon for your extension in the LynxHub registry.

### Requirements

* **Filename**: Must be named exactly `icon.png`.
* **Location**: Place it at the root of your `metadata` branch.
* **Format**: PNG format.
* **Dimensions**: Use a square image (e.g., 512x512 pixels).