Comments
OINK uses giscus for comments. Each page maps to one GitHub Discussion. Readers sign in with a GitHub account to post comments. Maintainers moderate comments in GitHub Discussions. The theme has no comment backend of its own. It bundles only giscus.
You must use a public GitHub repository. Visitors cannot read a private repository’s Discussions.
A page with comments enabled loads a script and an iframe from
https://giscus.app, which does not work in a network-isolated environment.
Comments are off by default. They load only when you explicitly enable them.
If the site has a privacy policy, document this external data boundary in it.
Preparing the GitHub repository
-
Choose a public repository for the comment threads. You can use the site’s source repository.
-
In the repository’s Settings → General → Features, select Discussions.
-
Install the giscus GitHub App for that repository. Without the App, visitors cannot comment or react.
-
Choose a Discussion category. giscus recommends the Announcements type. Only maintainers and the giscus bot can open a Discussion there. Readers cannot start one accidentally.
The repository ID and category ID are public identifiers, not credentials. Never put a personal access token, an OAuth secret or a password in Hugo configuration.
Generating the configuration
Open giscus.app. Enter the repository, mapping, and
category. The page generates a <script> block below. Copy four attributes
from that block to the OINK configuration:
The mapping determines which Discussion corresponds to each page. OINK
defaults to pathname. This suits stable published paths and one repository
that serves several domains or preview environments.
If you change mapping or move a page after comments exist, giscus searches
for a different Discussion. It does not delete existing comments, but the page
can no longer find them. Choose the mapping before launch. If a URL must
change, retain a redirect or rename the Discussion at the same time.
Enabling it site-wide
Copy all four repository/category fields from the configuration generated for your repository. Before you enable comments, replace every placeholder below:
The required fields repo, repoId, category, and categoryId must describe
the same repository and its selected Discussion category. If a field is missing
or contains only whitespace, Hugo prints one WARNING and skips giscus. The
build succeeds with a warning. Review production build diagnostics and correct
missing values before publication.
Currently, type accepts only giscus. Any other value also produces a warning
and skips giscus. The params.comments key names match Hextra’s. A configuration
migrated from Hextra can therefore remain unchanged.
The remaining keys (strict, reactionsEnabled, emitMetadata, term,
lang, lightTheme, darkTheme, ariaLabel, errorMessage) all have
defaults, defined fully in Configuration. A feature
switch takes either a YAML boolean or giscus-style 0 / 1.
Per-page control
The front matter comments value can enable or disable comments regardless of
the site switch. The value nearest the page takes precedence.
To enable comments only on selected pages, disable the site switch. Keep the complete repository configuration. Then enable comments on each selected page:
To disable comments on selected pages, keep the site switch enabled. Then disable comments on each selected page:
Use a cascade to configure an entire section. This site sets comments: true
in the cascade of content/docs/_index.md. Therefore, a giscus section appears
at the end of this page.
If the site also configures services.disqus.shortname, active giscus suppresses
Disqus. The setting comments: false disables both. If a required giscus key is
missing, the theme warns and skips giscus. Disqus can then load.
Multilingual text
The giscus interface automatically uses the current Hugo language. Simplified,
Traditional, and Hong Kong Traditional Chinese each use the corresponding
giscus locale. Unsupported languages fall back to English. Set lang explicitly
only if the automatic choice is incorrect.
Translate OINK’s two comment strings: the section’s accessible label and the loading-failure message. Configure them per language. The theme merges them with the global repository configuration:
A language layer needs only the values that differ. Keep repo / repoId /
category / categoryId in params.comments.
Following light and dark
With theme: auto, the giscus iframe follows OINK’s light/dark control and the
browser’s prefers-color-scheme. The comment section changes with the page.
To match the site’s palette more closely, set two giscus themes with
lightTheme / darkTheme. Each value can be a built-in giscus theme name or
CSS hosted by the site. This site uses hosted CSS:
If you set a fixed theme name in theme, giscus no longer follows the toggle.
A custom giscus theme has to be readable cross-origin
The giscus iframe loads from giscus.app. CORS must permit it to read a CSS
file from your site. For local preview, this site adds
Access-Control-Allow-Origin: '*' under server.headers in hugo.yml.
For production, configure this response header on the host.
Privacy and CSP
- OINK never requests or stores a reader’s GitHub password or access token. All sign-in and posting operations occur on giscus / GitHub.
- The theme ships the comment initialization script as a same-origin asset. It adds the script only to pages with comments enabled.
- With
loading: lazy, the iframe loads only as the reader scrolls near the comment section. - If the site has a strict Content Security Policy, both
script-srcandframe-srcmust permit giscus. Merge these permissions into the existing policy. Do not replace other directives. See Content Security Policy for the general rules:
If the external script fails to load or creates no iframe, OINK ends the loading
state. It shows errorMessage in a live status region. The page does not remain
on “loading”.
Verify
Then check the following items:
- Open a page that should have comments. Confirm that giscus appears at the end with “Sign in with GitHub”. Its interface must use the current page’s language.
- Toggle OINK’s light/dark control. With
theme: auto, confirm that the comment section follows it. - Open a page with
comments: false. Confirm that neither giscus nor another comment component appears. - Post a test comment. Return to GitHub. Confirm that a Discussion appears in the selected category and that you can manage it there.
Before the first comment or reaction creates a Discussion, a browser console message saying the Discussion was not found is expected.
If comments do not work, check WARNINGs in the build log for the four required
keys. Then check params.comments.enable and type, followed by the page’s
comments front matter. Confirm that the repository is public, Discussions are
enabled, and the giscus App is installed. Finally, check the browser console
and response headers for a CSP block on giscus.app. If existing threads are
missing, first restore the original mapping and page path.
Related
- Repository links and page info — edit this page, open an issue, contributors and the “was this helpful?” widget
- Analytics and SEO — the other capability needing an external service
- Deploy — Content Security Policy and external integrations in preview deployments
- Configuration — every
params.comments.*key - Page parameters —
commentsin front matter