Crate lintel_catalog_builder 

lintel-catalog-builder

Build a custom JSON Schema catalog from local schemas and external sources like SchemaStore.

Part of the Lintel project.

Config format

Create a lintel-catalog.toml in your catalog repo:

[catalog]
# Output targets
[target.local]
type = "dir"
dir = "../catalog-generated"
base_url = "https://raw.githubusercontent.com/your-org/catalog-generated/main/"

[target.pages]
type = "github-pages"
base_url = "https://catalog.your-domain.com/"
cname = "catalog.your-domain.com"

# Schema groups (locally defined)
[groups.my-schemas]
name = "My Schemas"
description = "Custom configuration schemas"

[groups.my-schemas.schemas]
config = { name = "Config", description = "App config", file-match = ["config.json"] }
external = { url = "https://example.com/schema.json", name = "External", description = "An external schema", file-match = ["*.ext.json"] }

# Group for organized schemas from external sources
[groups.github]
name = "GitHub"
description = "GitHub configuration files"

# External sources
[sources.schemastore]
url = "https://www.schemastore.org/api/json/catalog.json"

# Organize entries route schemas into groups by match patterns.
# Group metadata (name, description) comes from [groups.*] above.
[sources.schemastore.organize.github]
match = ["**.github**"]

Target types

dir

Writes output to a local directory (resolved relative to the config file):

• dir — output directory path
• base_url — URL prefix for schema references in catalog.json

github-pages

Generates output optimized for GitHub Pages deployment:

• base_url — URL prefix for schema references
• cname (optional) — custom domain; writes a CNAME file
• dir (optional) — output directory (defaults to .lintel-pages-output/<target-name>/)

Additional files generated: .nojekyll, CNAME, index.html, README.md.

CLI usage

# Build all targets
lintel-catalog-builder generate --config lintel-catalog.toml

# Build a specific target
lintel-catalog-builder generate --config lintel-catalog.toml --target pages

# Skip cache reads (force re-download)
lintel-catalog-builder generate --no-cache

# Control concurrency
lintel-catalog-builder generate --concurrency 50

GitHub Pages deployment

1. Add a github-pages target to your config

[target.pages]
type = "github-pages"
base_url = "https://catalog.your-domain.com/"
cname = "catalog.your-domain.com"

2. Create the GitHub Actions workflow

Save as .github/workflows/deploy-catalog.yml:

name: Deploy Catalog to GitHub Pages

on:
  push:
    branches: [master]
  workflow_dispatch:
  schedule:
    - cron: "0 6 * * *"

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5

      - name: Install lintel-catalog-builder
        run: |
          curl -fsSL https://github.com/lintel-rs/lintel/releases/latest/download/lintel-catalog-builder-x86_64-unknown-linux-gnu.tar.gz \
            | tar xz -C /usr/local/bin/

      - name: Generate catalog
        run: lintel-catalog-builder generate --config lintel-catalog.toml --target pages

      - uses: actions/configure-pages@v5

      - uses: actions/upload-pages-artifact@v4
        with:
          path: .lintel-pages-output/pages/

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - id: deployment
        uses: actions/deploy-pages@v4

3. Enable GitHub Pages

Go to repo Settings > Pages > Source and select GitHub Actions.

4. Configure DNS (if using a custom domain)

Create a CNAME DNS record pointing your domain to <your-org>.github.io. The CNAME file in the generated output tells GitHub Pages to use the custom domain automatically.

License

Apache-2.0

Modules

config