Fern Plugin

@theholocron/holocron-plugin-fern · npm · GitHub

Implements the wiki capability using Fern.

Install

pnpm add -D @theholocron/holocron-plugin-fern

Capability	Token
`wiki`	`HOLOCRON_FERN_TOKEN` (CI secret)

Config

providers: {
  // Short form — org name inferred from config.org
  wiki: "fern",

  // With a shared custom domain — repo name appended as basepath automatically
  wiki: ["fern", { domain: "wiki.theholocron.dev" }],

  // When the Fern workspace slug differs from config.org
  wiki: ["fern", { domain: "wiki.theholocron.dev", fernOrg: "holocron" }],
}

Options

Option	Required	Description
`domain`	No	Base domain (`"wiki.theholocron.dev"`) or full path (`"wiki.theholocron.dev/myrepo"`). A bare host gets the repo name appended automatically as a basepath.
`fernOrg`	No	Fern workspace slug. Defaults to `config.org`. Set this when the Fern workspace name differs from the GitHub org (e.g. workspace `"holocron"`, org `"theholocron"`).

What `holocron setup` does

Running holocron setup with providers.wiki: "fern" performs three steps:

fern/fern.config.json — workspace org name and pinned Fern CLI version. Always overwritten so the pinned version stays current.
fern/docs.yml — on first run, scaffolds the full file. On subsequent runs, updates only the instances: block (URL, custom-domain, multi-source) while leaving hand-edited navigation, colors, and layout untouched.
DNS CNAME — when domain is set and a dns provider is loaded, upserts a CNAME pointing the hostname at <fernOrg>.docs.buildwithfern.com.

Both fern/ files are committed to the repo — the wiki.yml CI workflow reads them at deploy time.

Custom domain and multi-source routing

Add "wiki" to your workflows array to get the wiki.yml thin caller, which publishes to production on push to main and generates a Fern preview URL on every pull request.

When domain is a bare host, the plugin appends the repo name as a basepath. Every repo in the org gets its own URL under a shared domain:

Repo	URL
`theholocron/holocron`	`wiki.theholocron.dev/holocron`
`theholocron/configs`	`wiki.theholocron.dev/configs`

The generated fern/docs.yml uses Fern’s multi-source: true flag, which Fern requires for basepath-aware routing:

instances:
  - url: theholocron.docs.buildwithfern.com/holocron
    custom-domain: wiki.theholocron.dev/holocron
    multi-source: true

DNS: one CNAME record — wiki.theholocron.dev → theholocron.docs.buildwithfern.com.

Authentication

HOLOCRON_FERN_TOKEN is a CI-only secret — it is not used by holocron setup and does not go in the keyring. Add it directly to your repo’s GitHub Secrets.

Resolution order:

--token flag
  → HOLOCRON_FERN_TOKEN        (env var)
  → FERN_TOKEN                 (Fern's native env var — vendor fallback)
  → keyring "fern.theholocron" (org-namespaced)
  → keyring "fern"             (unnamespaced fallback)

Store in keyring:

holocron auth set fern <token>

Go to dashboard.buildwithfern.com → Settings → API tokens
Create a token with publish permissions
Add it as a GitHub secret named HOLOCRON_FERN_TOKEN

The wiki.yml workflow passes it to fern generate --docs via secrets: inherit.

What `wiki` provides

provision(opts?) — writes fern/fern.config.json and scaffolds fern/docs.yml (skipped if already present). Called automatically by holocron setup when providers.wiki: "fern" is set.