Skip to content

Repository links and page info

Connect “edit this page”, “open an issue”, and “view history” to your repository. Show last-modified information, contributors, and feedback at the page end.

Repository entries in the action menu use a few github_* parameters. This menu appears at the breadcrumb row’s right end. The “last modified” line at the page end uses Git history. Both features assume that content is in a GitHub-style repository.

Every repository-related entry in the action menu derives from these keys:

hugo.yml
params:
  github_repo: https://github.com/pgsty/oink.pgsty.com # the documentation source repository
  github_project_repo: https://github.com/pgsty/oink # the product repository (optional)
  github_branch: main # defaults to main
  github_subdir: '' # path from the repository root to the Hugo site root

This site uses the configuration above. It gives this page’s action menu the following targets:

Menu entry Target
Edit this page …/edit/main/content/docs/customize/repository.md
View history …/commits/main/content/docs/customize/repository.md
Create child page …/new/main/content/docs/customize?filename=change-me.md&value=<template>
Open a documentation issue …/issues/new?title=Repository links and page info
Open a project issue https://github.com/pgsty/oink/issues/new

Follow these conventions:

  • github_repo must identify the content repository. If you use the theme repository, reader changes go to the wrong place. Without this key, the four documentation actions above are unavailable. The project issue depends only on github_project_repo.
  • github_project_repo identifies a second repository for product bugs instead of documentation errors. Do not configure it if readers cannot distinguish the two.
  • github_branch defaults to main. It identifies the content branch. Do not use the deployment branch or a branch generated by Pages.
  • github_subdir is the path inside the repository. If site source is at the repository root, leave it empty. If source is in a subdirectory, set its path, such as website for a repository with code and website/.

Set these values at site level, per language, in a section cascade, or in page front matter. These scopes support content from several repositories. See the complete definitions in Configuration.

Content from another repository

When content comes from an upstream repository, override the repository parameters with a section cascade. path_base_for_github_subdir removes or replaces the physical source path prefix before appending it to github_subdir. For source files copied inside the site, the path is relative to the site root:

content/reference/_index.md
---
title: Upstream reference
cascade:
  github_repo: https://github.com/OWNER/UPSTREAM
  github_project_repo: https://github.com/OWNER/UPSTREAM
  github_subdir: docs
  path_base_for_github_subdir: content/reference
---

content/reference/api/client.md therefore maps to the upstream’s docs/api/client.md.

Since OINK 1.2.0, the theme normalizes Windows and Unix source paths to / before matching and preserves filename case. For a physical mount outside the site, match its absolute source path rather than Hugo’s virtual mount target:

External source at /srv/upstream/docs/
path_base_for_github_subdir: '^/srv/upstream/docs/'

With github_subdir: docs, /srv/upstream/docs/api/client.md therefore maps to docs/api/client.md. After mapping and cleanup, the source must be a nonempty repository-relative path. Unmapped external files, absolute or drive-qualified results, . and parent-directory escapes suppress Edit, History, and Create child actions. Documentation and project issue links retain their own repository settings. Use / separators in Windows mapping expressions too.

The path_base_for_github_subdir value is a regular expression. If the source filename differs from the local filename, use a from / to mapping. For example, map each section’s _index.md to the upstream README.md:

content/reference/_index.md
path_base_for_github_subdir:
  from: content/reference/(.*?)/_index.md
  to: $1/README.md

OINK keeps .md and .zh.md together in one directory. Both languages share a path prefix, so the expression needs no language directory. After changing it, click “edit this page” from a leaf page, section index, and each language. If the expression removes too much, the URL can appear correct but return a 404.

Turning individual entries off

Every menu entry carries a stable action ID:

Menu entry Action ID
Copy as Markdown copy_markdown
View Markdown source view_markdown
Open in ChatGPT / Claude open_chatgpt / open_claude
View history view_history
Edit this page edit_page
Create child page create_child_page
Open a documentation issue create_issue
Open a project issue create_project_issue
Print the whole section print_section

If a host does not support an action, hide it with CSS:

assets/scss/_styles_project.scss
.td-page-actions__item[data-td-action='create_child_page'] {
  display: none;
}

The command palette uses the same IDs. Hiding a menu entry does not remove it from the palette. If the entire site cannot use a target, omit its configuration key. CSS can hide a link but cannot correct its target.

The whole menu can also be turned off per page with page_context_menu: false in front matter — see Page parameters.

The “create child page” action prefills content from the theme’s assets/stubs/new-page-template.md. To supply a site template, put your own file at assets/stubs/new-page-template.md.

Last modified

The last-modified line uses Git data, not file mtime. Enable Hugo’s Git support:

hugo.yml
enableGitInfo: true
params:
  github_repo: https://github.com/pgsty/oink.pgsty.com
  ui:
    lastmod_commit: subject # subject | hash | none

The page end then reads “Last modified August 17, 2026 · (a1b2c3d)”, with the commit part linking to …/commit/<hash>. The three values of lastmod_commit:

Value What is shown
subject (default) The commit subject plus the abbreviated hash
hash commit a1b2c3d
none The date only, with no commit link

Any other value warns (invalid params.ui.lastmod_commit) and uses subject.

Check these two conditions:

  • CI needs sufficient Git history. A shallow clone (fetch-depth: 1) cannot reach a file’s last commit. Its date can be missing or incorrect. Set fetch-depth: 0 in GitHub Actions.
  • An uncommitted file has no Git time. The line is absent when you preview a new local page.

If Git history is unavailable, do not use build time for “last modified”. Build time does not identify when content changed.

This line belongs to the annotation component, which is on by default and sits after feedback and before the pager. Turn it off for a page with annotation: false.

The annotation block also renders two kinds of provenance. Both use page front matter and require no template override:

  • Upstream attribution: for a derived page, set upstream_link and four required keys: upstream_name, upstream_copyright, upstream_license, and upstream_notice. The page end names the work, copyright holder, and license, with a link to the full notice. Add upstream_modified: true to append a “modified downstream” line.
  • Translation notice: params.ui.translation_notice contains the authoritative version’s language code. A translated page shows a link to that original. For a page authored natively in the current language, set translation_notice: false.

Both families are defined in full in Page parameters.

If you need customization, use one of three override points. Each covers one layer:

Partial to override What it changes
layouts/_partials/annotation-items.html Add, remove or reorder the lines, keeping the theme’s markup, icons, print rules and accessible label
layouts/_partials/page-meta-lastmod.html Replace the markup those lines render as
layouts/_partials/page-annotation.html Replace the block’s outer container

What the page end is made of

The five components have a fixed order. All reading layouts share one implementation:

Order Component Theme default Page switch
1 Share Off (params.ui.share is empty) share: false, or the page’s own list
2 Feedback Off feedback: true / false
3 Annotation On annotation: false
4 Pager On for docs / book / blog pager: false
5 Comments On when fully configured comments: false

This order follows reader actions after the last paragraph: share the page, give feedback, check provenance, open the next page, and join the discussion. Share appears first because it is the only outward action. Readers who intend to share have already made that choice before the feedback question. To configure the bar, see Writing a blog.

Configuring comments is in Comments.

The feedback widget

The widget asks “Did this page solve your problem?” with yes / no buttons. Choosing no expands four optional reasons. The widget is off by default:

hugo.yml
params:
  ui:
    feedback:
      enable: true
      reasons: true # whether to ask for a reason after "no"

To enable it for the documentation section only, use a cascade (a blog usually keeps just comments):

content/docs/_index.md
---
title: Docs
cascade:
  feedback: true
---

The widget has these boundaries:

  • A click completes it. There is no text box, no submit button and no sign-in.
  • The browser stores the choice in localStorage per page and language. Returning readers can see and change it.
  • If the site has Google Analytics (gtag), the widget sends a docs_feedback event with result (solved / not_solved), page_path, and language. Choosing a reason sends a second event with reason and refinement: true. This distinguishes it from the first count. Without analytics the widget still works and sends no reports. It requires no backend.
  • If the page enables comments, an anchor link labeled “add details in the comments” appears below the result. Feedback and giscus have independent data flows. The theme never writes comments for readers.

This page sets feedback: true in its front matter (the docs section defaults it off), so the real widget is visible at the page end.

The contributor wall

The contributors shortcode renders a GitHub avatar grid from a file under the site’s data/ directory. It never contacts GitHub at build time:

data/contributors.yaml
items:
  - github: Vonng
    name: Ruohang Feng
    role: Theme author
  - github: pgsty
    name: Pigsty
    role: Project organization
  - github: gohugoio
    role: Static site generator
    avatar: /icons/logo.svg
Source
{{< contributors >}}

The github field is required and must be a valid GitHub username. A duplicate produces a warning and skips the repeated entry. The name defaults to github. The role is optional. The url defaults to https://github.com/<github>. The avatar is optional. Without it, the shortcode renders an initial placeholder and makes no network request. If present, its value must be http(s):// or a site-root-relative path.

For several lists, use separate data files. Select each file with data=:

Source
{{< contributors data="maintainers" >}}

In Markdown and RSS output, the grid becomes a list of - [@handle](url) — role.

This site has no data/contributors.yaml

The example therefore does not render on this page. Add a data file to data/ to render it.

Verify

Run from your site’s root. Replace the example PAGE with an actual generated page whose source belongs to the configured repository:

hugo --printPathWarnings
PAGE=public/docs/getting-started/index.html
test -f "$PAGE" && grep -o '<a[^>]*data-td-action[^>]*>' "$PAGE"
  • Open the page’s title action menu. Confirm that “Edit this page” points to github.com/<your repository>/edit/<branch>/<source path>. Every source path segment must match. In command output, inspect the anchor with data-td-action="edit_page".
  • Repeat from a section index (_index.md): it also needs the correct source path.
  • Check the “last modified” line at the page end. It is expected to be absent on a new local page before commit.
  • Page parameters — annotation / feedback / pager / page_context_menu and the other page switches
  • Configuration — full definitions of github_*, ui.lastmod_commit and ui.feedback
  • Comments — the last block at the page end
  • Analytics and SEO — where feedback events are sent
  • AI-agent support — the Markdown and assistant entries in the action menu

Was this page helpful?