NextGuide Add-ons

Manifest reference

All required metadata for the current content-only add-on format and future extension descriptors.

Add-on manifest

The root nextguide-addon.json file identifies the publisher, the version and what the add-on is allowed to include. The current registry supports schema version 1, content-only add-ons.

nextguide-addon.jsonJSON
{
  "$schema": "./schema/nextguide-addon.schema.json",
  "schemaVersion": 1,
  "id": "acme.hello-world",
  "name": "Hello World",
  "summary": "A small documentation add-on.",
  "description": "Sample Markdown pages for a NextGuide Account Mode site.",
  "version": "0.1.0",
  "author": {
    "name": "Acme"
  },
  "repository": "https://github.com/acme/hello-world",
  "license": "MIT",
  "category": "content",
  "keywords": [
    "documentation",
    "example"
  ],
  "compatibility": {
    "mode": "account",
    "nextguide": ">=1.0.0 <2.0.0"
  },
  "permissions": [],
  "entrypoints": {
    "content": "content"
  },
  "icon": "icon.png"
}

Fields

FieldCurrent requirement
schemaVersion1 for releases accepted by the private registry today
idStable lowercase publisher.addon-name identifier
nameHuman-readable display name
summary, descriptionMeaningful summary and full description
versionIncreasing SemVer version, e.g. 0.1.0
author.namePublisher display name
repositoryActual public GitHub source repository, not the template
licensePackage license identifier
categorycontent for current schema v1 releases
keywordsDiscoverability terms
iconLocal PNG asset; not a remote URL
compatibility.modeaccount
compatibility.nextguideNextGuide compatibility version range
permissionsEmpty array [] for v1
entrypoints.contentRelative folder of Markdown source files

Folder layout

Expected v1 source layout
  • my-nextguide-addon
    • nextguide-addon.jsonRequired identity and compatibility
    • icon.pngLocal PNG icon
    • content
      • index.mdMarkdown content
    • docs
      • AUTHORING.md
      • REVIEW.md
    • schema
      • nextguide-addon.schema.json
    • scripts
      • validate-addon.mjs
      • ng-addon.mjs
    • test
      • publish-addon.test.mjs
      • validate-addon.test.mjs
    • package.json

Use a local PNG icon between 32 and 1024 pixels per side, up to 256 KiB. The content directory may contain plain Markdown, but no executable MDX or script payloads. Source commits and release archives must match; publishing unsigned local files is not supported.

A future executable manifest

The NextGuide source package includes a draft schema v2 validator. This example is not currently publishable through ngapi:

Future: nextguide-addon.json (not publishable)JSON
{
  "schemaVersion": 2,
  "id": "acme.search-tools",
  "name": "Search Tools",
  "version": "1.0.0",
  "category": "integration",
  "compatibility": {
    "mode": "account",
    "nextguide": ">=1.0.0 <2.0.0"
  },
  "permissions": [
    "admin.pages",
    "storage.read",
    "storage.write"
  ],
  "entrypoints": {
    "server": "dist/server.mjs",
    "client": "dist/client.js"
  }
}

The extensions API defines capability requests but does not grant execution permission. Read Permissions & security and the Extension API for current boundaries.

Common validation problems

  • Invalid add-on ID: Use publisher.addon-slug, not just addon-slug.
  • Repository mismatch: The manifest URL must match the selected GitHub repository.
  • Version already registered: Publish a higher semantic version; released versions are immutable.
  • Unsupported permissions or entrypoints: Current v1 releases allow permissions: [] and entrypoints.content only.

The NextGuide Publisher GitHub App checks all supported issues together and offers explicit corrections for safe metadata changes. It should not silently rewrite your source.