JimGalasyn opened a new pull request, #904:
URL: https://github.com/apache/kafka-site/pull/904
The **Create documentation issue** link in the page footer is broken on every
docs page. A reader trying to report a docs bug hit this and had no way to
file.
## The problem
Docsy builds that link as `{github_repo}/issues/new`, but GitHub Issues are
disabled on `apache/kafka-site`, so the URL 404s:
```
https://github.com/apache/kafka-site//issues/new?title=Introduction -> 404
https://github.com/apache/kafka-site/issues/new?title=Introduction -> 404
```
Both spellings 404 — the doubled slash (from a trailing `/` in `github_repo`)
is a separate cosmetic defect, not the cause. The link cannot work while
Issues
are disabled, so it has never worked.
## The fix
Kafka tracks bugs in JIRA, so the link now points at the KAFKA project.
Docsy v0.11.0's `page-meta-links.html` offers no configuration option to
override just that one URL, so the partial is vendored into
`layouts/partials/`
with a single line changed:
```diff
- {{ $issuesURL := printf "%s/issues/new?title=%s" $gh_repo (safeURL $.Title
) -}}
+ {{ $issuesURL := "https://issues.apache.org/jira/projects/KAFKA"; -}}
```
A comment at the top of the file records why the override exists and what to
re-apply on a Docsy upgrade. Apart from that comment and the one line, the
file
is byte-identical to upstream Docsy v0.11.0.
Two smaller changes in `hugo.yaml`:
- Drop the trailing slash from `params.github_repo`, which was producing a
doubled slash in every generated link. GitHub tolerates it on `/tree/` and
`/edit/`, so those links did work; this just makes the URLs canonical.
- Point the two `ui.feedback` responses at JIRA too — they carried the same
dead
`/issues/new` URL. These sit behind `ui.feedback.enable: false`, so they
are
not currently user-visible.
## Alternatives considered
- **Enable Issues on the repo** via `.asf.yaml`. Smallest change that would
make
the existing button work, but it opens a bug-intake channel the project has
not opted into, alongside JIRA. Happy to switch to this if maintainers
prefer.
- **Delete the button.** Removes the dead link without offering a
destination.
Pointing at JIRA seemed more useful to readers, but this is easy to change.
## Verification
Built locally with the Hugo version CI uses (`v0.123.7-extended`, per
`.github/workflows/build-and-deploy.yml`):
- Build succeeds: 3792 pages, 25649 static files.
- Rendered output: **0** pages containing the old `issues/new` URL, **2157**
containing the JIRA URL.
- Sample rendered anchor:
```html
<a href="https://issues.apache.org/jira/projects/KAFKA";
class="td-page-meta--issue td-page-meta__issue" target="_blank" rel="noopener">
```
Note for anyone reproducing: the repo does not build with Hugo 0.164+ (the
version currently pinned in `package.json` as `hugo-extended`). It fails with
`no such template "_default/_markup/td-render-heading.html"` — docsy v0.11.0
against Hugo's newer render-hook rules. That failure is present on an
unmodified
checkout of `markdown` too, so it is unrelated to this change, but the
`package.json` pin looks out of step with the CI image.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
