feat(docs): add page actions to all docs pages by BittuBarnwal7479 · Pull Request #331 · Kaelio/ktx

BittuBarnwal7479 · 2026-07-02T11:24:58Z

fixes: #330

Summary

Add Suggest edits and Raise issue actions to all documentation pages for a consistent user experience.

vercel · 2026-07-02T11:25:02Z

@BittuBarnwal7479 is attempting to deploy a commit to the Kaelio Team on Vercel.

A member of the Team first needs to authorize it.

BittuBarnwal7479 · 2026-07-02T11:31:55Z

luca-martial

Thanks for this, it's a genuinely useful addition (fixes #330), and the footer handling is done right: re-adding <PageFooter /> keeps prev/next nav because the Footer slot derives neighbours from context.

Two blockers stop it from shipping, plus a few design-cohesion items. Details are inline.

Blocking

lucide-react is imported but not a dependency of docs-site; under the workspace's shamefullyHoist: false this fails a clean next build, and it contradicts the repo's "icons are inlined" convention. (docs-page-actions.tsx)
"Raise issue" points at the bug_report.yml issue form, which ignores the body query param. The page/source context is silently dropped and the reader is forced into a bug form requiring repro steps and a KTX version, with blank_issues_enabled: false blocking any escape. (page.tsx)

Design / UX
3. The three actions are split across two locations (Copy top-right, Suggest edits / Raise issue in the footer) with identical styling, and the hero page shows only 2 of them. Group them into one cluster.
4. Icon set is inconsistent (two buttons have icons, Copy has none), and CircleAlert reads as an error state rather than feedback.

Code quality
5. Hardcoded canonical URL duplicates llm-docs.ts siteOrigin/absoluteUrl.
6. The markdown file is read up to 3x per page.
7. footer.component is a deprecated fumadocs prop.
8. The new test asserts URL shape, not that the issue flow is usable.

luca-martial · 2026-07-03T05:15:20Z

 "use client";

 import { useState } from "react";
+import { CircleAlert, PencilLine } from "lucide-react";


Blocking (build break). lucide-react is not a dependency of docs-site (docs-site/package.json lists only fumadocs/next/react). It exists only transitively under fumadocs-ui in the pnpm store, and the workspace runs shamefullyHoist: false, so this bare import is not resolvable from docs-site/node_modules. A clean pnpm install + next build fails with Can't resolve 'lucide-react' (the new dev-server test should already be red on this).

This also contradicts the existing convention documented in theme-toggle.tsx: "Icons are inlined (the project doesn't depend on lucide-react directly)". Please inline the two SVGs the same way theme-toggle.tsx does, or add lucide-react to docs-site deps. The inline approach matches the repo.

luca-martial · 2026-07-03T05:15:20Z

+          rel="noreferrer noopener"
+          className={actionClassName}
+        >
+          <CircleAlert className="size-3.5" aria-hidden="true" />


CircleAlert reads as an error/warning state ("something is broken on this page"), not "send feedback". A bug, flag, or message glyph fits "Raise issue" better.

Also: these two links carry icons but "Copy as Markdown" (same actionClassName) has none, so the family looks half-styled. Pick one rule: icons on all three, or none.

luca-martial · 2026-07-03T05:15:20Z

+  ].join("\n");
+
+  const params = new URLSearchParams({
+    template: "bug_report.yml",


Blocking (feature doesn't do what it looks like it does). bug_report.yml is a GitHub issue form (YAML with a body: field list). Issue forms ignore the body query parameter entirely; they prefill only via per-field params keyed by each field's id. So the context built just above (page URL, source file, "What should change?") is silently discarded.

What the reader actually gets: the bug form, whose required fields are "How can we reproduce it?" and "KTX version" (labeled bug), for what is often a one-line docs typo. And config.yml sets blank_issues_enabled: false, so they can't fall back to a blank issue.

Recommend a dedicated docs-feedback issue form and prefill its fields by id, e.g. ?template=docs_feedback.yml&page=...&source=.... Ref: https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-githubs-form-schema

luca-martial · 2026-07-03T05:15:20Z

  const MDX = page.data.body;
  const mdxSource = await readDocsPageMarkdown(page.slugs);
+  const sourcePath = await resolveDocsPageMarkdownPath(page.slugs);
+  const pageUrl = `https://docs.kaelio.com/ktx/docs/${page.slugs.join("/")}`;


This hardcodes the canonical origin, but lib/llm-docs.ts already owns it (siteOrigin = "https://docs.kaelio.com/ktx" plus an absoluteUrl() helper), and page.url already carries the canonical path. Two definitions of the same origin will drift. Reuse the existing helper / page.url for a single source of truth.

luca-martial · 2026-07-03T05:15:21Z

    <DocsPage
      toc={page.data.toc}
      className="!mx-0 min-w-0 justify-self-start md:!mx-auto"
+      footer={{


footer.component is deprecated in this fumadocs version (the DocsPageProps type marks it @deprecated use slots.footer instead). It works today, but prefer slots={{ footer: ... }} to avoid breakage on the next fumadocs major.

(For the record, re-adding <PageFooter /> here is correct: the Footer slot derives prev/next from context via useFooterItems(), so navigation is preserved.)

luca-martial · 2026-07-03T05:15:21Z

+        component: (
+          <>
+            <div className="mt-10 mb-4">
+              <DocsPageActions


Design. These two actions now live in the footer while "Copy as Markdown" stays top-right next to the title (line 101), all three sharing the same actionClassName. Same visual family, two locations, so it reads accidental rather than grouped.

It's also inconsistent per page: the hero page skips the header block ({!hero && ...}), so it shows only these 2 footer actions, while every other page shows 1 on top and 2 at the bottom. Suggest grouping all three into one cluster (all top-right, or all in the footer).

luca-martial · 2026-07-03T05:15:21Z


  try {
-    return await readFile(directPath, "utf8");
+    await readFile(directPath, "utf8");


Minor: this reads the file just to test existence and throws the content away; readDocsPageMarkdown then reads it again; and page.tsx calls both readDocsPageMarkdown and resolveDocsPageMarkdownPath, so the direct-path file is read up to 3x per page. Build-time only, so low priority, but consider returning { path, content } from one function, or probing with access/stat instead of readFile.

luca-martial · 2026-07-03T05:15:21Z

+    );
+    assert.match(
+      html,
+      /https:\/\/github\.com\/Kaelio\/ktx\/issues\/new\?[^"]*template=bug_report\.yml/,


This asserts the href contains template=bug_report.yml, which is true regardless of whether the resulting issue is usable, so it would pass on the broken flow described in the page.tsx comment (the form ignores the prefilled body). Once "Raise issue" points at a docs-feedback template with id-based prefill, assert on the field params that actually populate.

BittuBarnwal7479 · 2026-07-03T11:57:58Z

Hey @luca-martial i've addressed the latest feedback and pushed the requested changes.

B

04b86be

BittuBarnwal7479 changed the title ~~feat(docs): add Suggest edits and Raise issue actions to all documentation pages~~ feat(docs): add page actions to all docs pages Jul 2, 2026

Merge branch 'main' into feat/docs-page-actions

c1b7286

luca-martial self-requested a review July 3, 2026 05:04

luca-martial requested changes Jul 3, 2026

View reviewed changes

luca-martial and others added 5 commits July 2, 2026 22:16

Merge branch 'main' into feat/docs-page-actions

54ad830

Merge branch 'main' into feat/docs-page-actions

1503160

feat: add documentation feedback form and enhance page actions

6eac594

fix(KTX CI): dead-code failure locally

1fbf87e

refactor: improve query object structure in test assertions

465aec4

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(docs): add page actions to all docs pages#331

feat(docs): add page actions to all docs pages#331
BittuBarnwal7479 wants to merge 7 commits into
Kaelio:mainfrom
BittuBarnwal7479:feat/docs-page-actions

BittuBarnwal7479 commented Jul 2, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Jul 2, 2026

Uh oh!

BittuBarnwal7479 commented Jul 2, 2026

Uh oh!

luca-martial left a comment

Uh oh!

luca-martial Jul 3, 2026

Uh oh!

luca-martial Jul 3, 2026

Uh oh!

luca-martial Jul 3, 2026

Uh oh!

luca-martial Jul 3, 2026

Uh oh!

luca-martial Jul 3, 2026

Uh oh!

luca-martial Jul 3, 2026

Uh oh!

luca-martial Jul 3, 2026

Uh oh!

luca-martial Jul 3, 2026

Uh oh!

BittuBarnwal7479 commented Jul 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

BittuBarnwal7479 commented Jul 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Uh oh!

vercel Bot commented Jul 2, 2026

Uh oh!

BittuBarnwal7479 commented Jul 2, 2026

Uh oh!

luca-martial left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

BittuBarnwal7479 commented Jul 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

BittuBarnwal7479 commented Jul 2, 2026 •

edited

Loading