OpenParable
Skip to content
← Back to skills

Authoring Docs

Business
authoring-docs

Authoring Docs is an Agent Skill for business published in the goreleaser/goreleaser repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Use when writing or editing GoReleaser documentation under www/content (Hugo site) — customization reference pages, YAML config examples, "Since vX.Y" / Pro badges, callouts, or documenting a feature that is merged but not yet released.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/goreleaser/goreleaser/blob/HEAD/.copilot/skills/authoring-docs/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/authoring-docs, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Authoring GoReleaser Docs

The docs are a Hugo site under www/. Content lives in www/content/; custom shortcodes in www/layouts/shortcodes/.

  • Preview locally: task docs:serve (runs docs:generate then hugo server).
  • Build / link-check: task docs:build / task docs:test.

Page structure

Pages are Markdown with YAML frontmatter:

---
title: "Discourse"
weight: 30
---

weight orders pages within a section (lower = higher in the nav).

Version & Pro badges

These mark when a feature appeared or that it is Pro-only. Two forms exist: block (its own line, renders a callout box) and inline (renders a small badge).

ShortcodeUse
{{< g_version "v2.13" >}}Block. Top of a new page (right after frontmatter) or under a section heading for a feature added later.
{{< g_inline_version "v2.6" >}}Inline. Inside YAML comments and Markdown table cells.
{{< g_featpro >}}Block. Pro-only feature note.
{{< g_inline_pro >}}Inline. Marks a single field/option as Pro-only.

The version is the GoReleaser tag the feature shipped in (e.g. v2.6, v2.15.4). g_inline_version links to the corresponding /blog/goreleaser-vX.Y release post.

Unreleased features (-unreleased suffix)

When documenting something already merged but not yet released, append -unreleased to the upcoming version number. Use the next unreleased minor (currently v2.17 — check the latest tag / ## A note about MSIX in customization/package/nfpm.md for the live example).

    # {{< g_inline_version "v2.17-unreleased" >}}
{{< g_version "v2.17-unreleased" >}}

Both shortcodes detect the -unreleased suffix and render a "beaker" (experimental) badge — "Since v2.17 (unreleased)" / "This will be available in the next release". When v2.17 ships, drop the -unreleased suffix.

YAML config examples

Customization pages document fields as a commented .goreleaser.yaml block, fenced with a filename attribute:

```yaml {filename=".goreleaser.yaml"}
announce:
  discourse:
    # Whether this announcer is enabled or not.
    #
    # Templates: allowed.
    enabled: true

    # Title to use for the Discourse topic.
    #
    # Default: '{{ .ProjectName }} {{ .Tag }} is out!'.
    # Templates: allowed.
    title_template: "..."
```

Conventions inside the block:

  • One comment block per field, directly above it. Fields separated by a blank line.
  • Description sentence(s) first, then a bare # separator line, then standardized annotations — each on its own line:
    • # Default: <value>.
    • # Templates: allowed.
    • # Required.
    • # Valid options: a, b, c.
  • Badges go at the end of a comment line (e.g. # Templates: allowed. {{< g_inline_version "v2.6" >}}) or on their own comment line right before the field (e.g. # {{< g_inline_pro >}}).

Callouts

Block-level notes, placed in prose with a blank line above and below:

  • {{< g_experimental "https://github.com/.../issues/123" >}} — experimental feature; the URL is the feedback link.
  • {{< g_featpro >}} — Pro-only feature.
  • {{< g_templates >}} — "learn more about templates"; place after a config block whose fields support templates.

Shortcode delimiters

  • {{< shortcode >}} (angle brackets) — default; raw HTML output. Used by all badges, callouts, and {{< tabs >}} / {{< tab >}}.
  • {{% shortcode %}} (percent) — only when output is Markdown to be rendered: g_include and g_button.

Reuse & tabs

  • Shared YAML snippets live in www/content/includes/*.md and are embedded with {{% g_include file="includes/repository.md" %}} (reused: repository.md, prs.md, commit_author.md).
  • OSS vs Pro variants: {{< tabs >}}{{< tab "OSS" >}}…{{< /tab >}}{{< tab "Pro" >}}…{{< /tab >}}{{< /tabs >}}.

Don't hand-edit (generated)

  • www/content/resources/{contributing,users,eula,security}.md — copied from repo-root files by task docs:generate.
  • www/static/schema.json — generated from pkg/config/config.go via task schema.