Publishing a theme

The directory at /themes lists themes that were submitted at /themes/submit and approved by a maintainer. A theme is a GitHub repository; each vX.Y.Z release is a version. When you submit, the directory checks the repository on the spot — the checks are listed under Submit — and, if it passes, queues it for a maintainer to review. Once approved it appears in the listing within minutes, and the directory re-checks it on a schedule and picks up new releases by itself.

You do not say whether you are submitting a theme or a plugin: the directory tells them apart by which manifest the latest release carries, goblog-theme.json or goblog-plugin.json. A repository must have exactly one of the two. Either submit form accepts either kind; the confirmation says which one it was filed as.

There is no build step and no release workflow. The directory downloads GitHub's archive of the tag, keeps only templates/ and static/, and parses the templates the way goblog will. How to write the templates themselves is covered in Writing a theme; this page is about what the repository must look like to be listed.

What the repository must contain

At the root of the repository, at the release tag being published (submission checks the latest release):

The archive of the tag must be 16 MiB or smaller, with at most 2000 entries, no symlinks, and no entry whose extracted size — alone or in total — exceeds 16 MiB. Only templates/ and static/ are extracted and installed; everything else in the repository (the manifest, README, screenshot, your tooling) is read individually and never copied to a site. Paths with a backslash, a NUL, a leading / or .. are refused, and so is a path that appears twice in the archive.

The manifest

{
  "name": "ocean",
  "display_name": "Ocean",
  "description": "One sentence shown in the listing.",
  "author": "Your Name",
  "license": "MIT",
  "min_goblog_version": "0.5.0",
  "homepage": "https://example.com/optional"
}

display_name, description and author must be non-blank; whitespace alone does not count.

Templates

Start from themes/default/templates in the goblog repository at the version you target and copy only the files you want to change. Templates are Go html/template; the rawHTML function and everything in templates/shared are available. Each file must parse on its own, on top of the shared and default sets — the directory checks that, in file-name order, and reports the first failure.

Validation parses each file; a reference to a template that does not exist ({{ template "nope" . }}) is only caught when the page renders, so test your theme locally before you tag. An empty override file does not blank the default template — Go keeps the earlier definition when a later one is empty; to remove a section, ship a file with content.

Releases

• Tag releases vX.Y.Z — exactly three numbers, nothing else. Drafts and pre-releases are ignored.
• The directory picks the newest published, non-prerelease release by publish date and checks its tag first, so a badly-tagged latest release is an error rather than silently skipped.
• The GitHub release body is shown as the version's release notes.
• The directory lists the latest release; the theme's detail page shows all of its vX.Y.Z releases.
• Nothing has to be attached to the release. download_url in the index is GitHub's zip of the tag (…/archive/refs/tags/vX.Y.Z.zip).
• The index's sha256 is a content hash, not a hash of the zip: each extracted templates/ and static/ file contributes its path, its length and its bytes, in path order. GitHub does not promise that a tag's zipball is byte-stable, so hashing the archive would break installs whenever GitHub re-compressed it. goblog's installer downloads the zip, extracts the same two folders, recomputes the hash and refuses the install if it differs from the index.

Submit

Paste your repository — owner/name, or any github.com/owner/name URL — into the form at /themes/submit. The form is plain HTML and works without JavaScript; the result is rendered into the same page. Nothing is stored unless validation passes.

Before validation starts, the directory refuses:

• text that is not a GitHub repository (enter a GitHub repository URL like https://github.com/owner/repo, or just owner/repo);
• a repository that is already listed (this repository is already listed in the directory, with a link to its page) or already waiting (this repository is already under review). A rejected repository may be submitted again;
• more than 5 submissions per hour from one address (too many submissions from your address; try again in an hour, HTTP 429). Refused attempts are not counted, so retrying does not push you further out;
• a submission while another one is being checked (another submission is being checked; try again in a minute, HTTP 429). Public validations run one at a time;
• a submission while 100 are already waiting for review (the review queue is full; try again in a few days). The queue is bounded as a whole, not only per address.

Validation then runs synchronously, with a 90 second budget end to end, in this order:

1. Kind. Fetch the latest published, non-prerelease release; its tag must be vX.Y.Z. Look for goblog-plugin.json and goblog-theme.json at that tag: exactly one must exist.
2. Manifest. Parse goblog-theme.json against the rules above.
3. README. README.md must exist at the tag.
4. Screenshot. screenshot.png, then screenshot.jpg, must exist at the tag and be 1 MiB or smaller.
5. Archive. GitHub's zip of the tag is downloaded (16 MiB or smaller) and unpacked in memory under the limits above, keeping templates/ and static/.
6. Templates. There must be at least one templates/*.html; each is checked against the 256 KiB cap and parsed on top of goblog's shared and default templates. Every {{ template "…" }} they reference must then exist somewhere in that set — in the theme, in its own {{ define }} blocks, or in goblog's shared and default templates (a theme may reference header.html, footer.html or admin_nav.html without shipping them; default's copy is used).
7. Docs. README.md, CHANGELOG.md (if present) and every release body are rendered through GitHub's markdown API; the README, the changelog and each release's notes must each render to 1 MiB or smaller. The repository's star count is fetched too — best effort, 0 if GitHub cannot be reached for it.
8. Name. The theme's name must not already be published by a different repository.

A failure is shown above the form with the reason — the texts are in Common validation errors. A pass shows Queued for review as a theme and stores the built entry under Pending review. A maintainer sees the card in Admin → Plugins → Directory: the screenshot, the kind, display name, name and version, author, license and min_goblog_version, a link to the repository, and a Show README button that expands the rendered README. They approve or reject from there; approval usually takes a few days. An approved entry is in the index within minutes.

What gets published

The index entry is built from the manifest and the latest release: version is the tag without v, download_url is the tag's zip, sha256 is the content hash, screenshot_url is the raw GitHub URL of the screenshot at the tag, released_at is the release's publish time, and stars is the repository's GitHub star count, which the listing sorts by. The entry carries install_type: "theme", kind: "theme" and an empty allowed_hosts. The detail document at /themes/<name>.json adds the rendered README, changelog and release history. The exact shapes are in Directory formats.

Updates

The directory's refresh-directory job re-checks every approved repository once the last refresh is older than the site's refresh_minutes setting (default 360, minimum 15). If the latest vX.Y.Z release is the one already listed, only the star count is refreshed. If there is a newer release, the whole validation above runs again against it and the listing is replaced. A failed rebuild keeps the old listing: the error is recorded on the entry and shown to the maintainer as "failed" next to "serving vX.Y.Z", but a broken release never takes a theme off the directory. Fix the release (or publish a new one) and the next refresh picks it up; a maintainer can also press Rebuild to re-check at once.

A theme is code: once an operator activates it, its templates render every page of their site, including the admin, with no sandbox. The directory checks that a theme is well-formed, not that it is benign; maintainers may decline or delist entries.

Common validation errors

Messages are prefixed with the repository (owner/name: …) and, once a release has been picked, its tag too (owner/name@v1.2.0: …); the release-level errors (no published release, release tag … must be vX.Y.Z) carry the repository only. Manifest problems are joined with ; after goblog-theme.json:; archive problems start with archive:; template problems start with templates do not load:.

If the message is Something went wrong on our side; please try again later., the failure was on the directory (GitHub unreachable, a database error) and is logged there — not something in your repository. Try again later.