Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
192 lines (153 loc) · 4.96 KB

CONTRIBUTING.md

File metadata and controls

192 lines (153 loc) · 4.96 KB

Contributing Extensions

This repository contains extensions for the Athas editor. Extensions can provide language tooling support (LSP, formatting, linting, snippets), themes, icon themes, keymaps, and more.

Syntax highlighting is bundled in Athas core and is not managed by these extensions.

Repository Structure

extensions/
  bash/
    extension.json      # Extension manifest
  lua/
    extension.json      # Extension manifest
    tooling.json        # Platform-specific tooling (pre-built LSP, formatter, linter binaries)
    build.sh            # Build script for tooling archives
  ...
registry.json           # Extension registry
index.json              # Extension index (for marketplace)
manifests.json          # Combined manifests (auto-generated, do not edit manually)
scripts/                # Validation and generation scripts
  • extension.json defines the extension manifest (category, contributions, capabilities, tool references)
  • tooling.json (optional) defines pre-built platform-specific binaries distributed as tarballs
  • Not every extension has a tooling.json. Extensions without one rely on runtime-installed tools

Adding a New Extension

  1. Create a folder under extensions/ (lowercase, use underscores for multi-word names like c_sharp).

  2. Add an extension.json manifest:

{
  "$schema": "https://athas.dev/schemas/extension.json",
  "id": "athas.mylang",
  "name": "MyLang",
  "displayName": "MyLang",
  "version": "1.0.0",
  "description": "MyLang language support with LSP",
  "publisher": "Athas",
  "engines": {
    "athas": ">=0.7.0"
  },
  "categories": ["Language"],
  "contributes": {
    "languages": [
      {
        "id": "mylang",
        "extensions": [".ml"],
        "filenames": ["MyLangfile"],
        "filenamePatterns": ["*.mylang.json"],
        "aliases": ["MyLang"]
      }
    ]
  }
}

  1. Add capability entries in capabilities only for tooling provided by the extension (lsp, formatter, linter, grammar assets as needed). Snippets, commands, themes, icon themes, agents, database providers, and keybindings should be declared under contributes.

  2. Regenerate generated files:

    bun run scripts/generate-manifests.ts
bun run scripts/build-extensions-index.ts

  3. Validate your extension:

    bun run scripts/validate.ts

Extension Manifest Format

Required Fields

Field Type Description
id string Unique identifier (format: publisher.name)
name string Short name
version string Semver version
categories string[] Extension categories (Language, Theme, Snippets, Keymaps, etc.)

Contributions

New manifests should prefer the declarative contributes model:

"contributes": {
  "languages": [],
  "snippets": [],
  "themes": [],
  "iconThemes": [],
  "databaseProviders": [],
  "agents": [],
  "commands": [],
  "keybindings": []
}

Top-level arrays such as languages, themes, iconThemes, agents, and databaseProviders are still supported for existing manifests. Validation, catalog generation, theme/icon packaging, and database sidecar packaging read both forms.

Language contributions can match by file extension, exact filename, or filename pattern:

{
  "id": "jsonc",
  "extensions": [".jsonc"],
  "filenames": ["tsconfig.json", "jsconfig.json"],
  "filenamePatterns": ["tsconfig.*.json", "jsconfig.*.json"]
}

Categories

  • Language - Language tooling support (LSP, formatter, linter, snippets, commands)
  • Theme - Editor themes
  • Snippets - Code snippets
  • Keymaps - Keyboard shortcut presets
  • Formatter - Code formatters
  • Linter - Code linters
  • Other - Everything else

Language Capabilities

LSP

"lsp": {
  "name": "pyright",
  "runtime": "bun",
  "package": "pyright",
  "packages": ["optional-peer-dependency"],
  "args": ["--stdio"]
}

Use packages for runtime-managed companion packages that must be installed beside the primary package, such as TypeScript SDK packages required by JavaScript-based language servers.

Supported runtimes: bun, node, python, go, rust, binary

Formatter

"formatter": {
  "name": "black",
  "runtime": "python",
  "package": "black",
  "args": ["--stdin-filename", "${file}", "-"]
}

Linter

"linter": {
  "name": "ruff",
  "runtime": "python",
  "package": "ruff",
  "args": ["check", "--stdin-filename", "${file}", "--output-format", "json", "-"]
}

Testing Locally

  1. Clone this repository alongside the main Athas repo:

    athasdev/
  athas/        # Main editor repo
  extensions/   # This repo

  2. Serve the extensions directory locally:

    bunx serve .

  3. Point the editor to your local server:

    VITE_PARSER_CDN_URL=http://localhost:3000/extensions bun run dev

Validation

bun run scripts/validate.ts

CI runs this automatically on pull requests.