LiteSun commented on code in PR #2078:
URL: https://github.com/apache/apisix-website/pull/2078#discussion_r3654932132
##########
next/src/lib/content.ts:
##########
@@ -95,6 +95,22 @@ const docsPythonEn =
import.meta.glob('/content/docs-python-plugin-runner-en/**/
const sidebarConfigs = import.meta.glob('/content/docs-*/config.json', {
eager: true }) as Record<string, any>;
+/** Git ref each project's docs were synced from (written by
sync-content.mjs). */
+const docRefs = (Object.values(
+ import.meta.glob('/content/doc-refs.json', { eager: true }) as
Record<string, any>,
+)[0]?.default ?? {}) as Record<string, string>;
+
+/**
+ * "Edit this page" URL for an upstream project doc. Uses the ref the content
+ * was actually synced from — sub-projects are cloned at a release tag, and
+ * default branches differ (master vs main) — and `pathId`, the source-relative
+ * path, since a frontmatter slug can move the URL away from the filename.
+ */
+export function docEditUrl(project: string, repo: string, pathId: string,
locale: Locale): string {
+ const ref = docRefs[project] ?? 'master';
+ return
`https://github.com/apache/${repo}/edit/${ref}/docs/${locale}/latest/${pathId}.md`;
Review Comment:
Using the rendered locale as the source locale still produces broken Edit
links for fallback pages. `getApisixDocs('zh')` and `getSubprojectDocs(...,
'zh')` deliberately use the English module when a translation is absent, but
these routes still call this helper with `zh`. In the release build, 57
Chinese-locale pages have no Chinese source: for example `/zh/docs/apisix/aws/`
links to `release/3.17/docs/zh/latest/aws.md` and `/zh/docs/helm-chart/apisix/`
links to `master/docs/zh/latest/apisix.md`; both paths are missing while their
English files exist. Please retain the effective source locale/path on
`DocEntry` and build the Edit URL from those values.
##########
next/src/pages/docs/[project]/[...id].astro:
##########
@@ -27,5 +27,5 @@ const repo = SUBPROJECTS[project].repo;
sidebar={sidebar}
titleById={titleById}
urlById={urlById}
-
editUrl={`https://github.com/apache/${repo}/edit/master/docs/en/latest/${entry.id}.md`}
+ editUrl={docEditUrl(project, repo, entry.pathId, 'en')}
Review Comment:
The version picker was added only to the APISIX-specific routes. This
generic route (and its Chinese counterpart) still passes no `versionLabel`,
`archivedVersions`, or `versionBase`, so all six sub-projects lose their route
back to the retained `next/` tree. The release build has 72 affected pages
across the two locales. Please supply the per-project version metadata here as
well, or explicitly document this as a deferred gap.
##########
next/scripts/generate-md-twins.mjs:
##########
@@ -0,0 +1,199 @@
+/**
+ * Post-build agent-readable surfaces.
+ *
+ * For every content page the build produced, emit a Markdown twin next to the
+ * HTML (`<page>/index.md`) and index them all in `/llms.txt`. Agents that read
+ * docs — and the crawlers behind them — get clean prose instead of parsing a
+ * page of markup.
+ *
+ * The twin is the *synced source* markdown, with frontmatter replaced by a
+ * title heading and a link back to the canonical HTML. Source markdown lives
+ * in content/ (written by sync-content.mjs), so this runs after `astro build`
+ * and needs no MDX evaluation.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+const args = process.argv.slice(2);
+const distFlag = args.indexOf('--dist');
+const dist = distFlag !== -1 ? path.resolve(args[distFlag + 1]) :
path.join(root, 'dist');
+const content = path.join(root, 'content');
+const SITE = 'https://apisix.apache.org';
+
+/**
+ * content/ subdir -> every URL prefix its pages are published under. Several
+ * collections have one source that renders at both locales (the zh site falls
+ * back to the English text where no translation exists), so a source file can
+ * legitimately map to two URLs.
+ */
+const COLLECTIONS = [
+ ['blog-en', ['/blog']],
+ ['blog-zh', ['/zh/blog']],
+ ['learning-center', ['/learning-center', '/zh/learning-center']],
+ ['articles', ['/articles', '/zh/articles']],
+ ['docs-general', ['/docs/general', '/zh/docs/general']],
+ // The zh APISIX docs fall back to the English source where no translation
+ // exists, so the English collection must also be offered the zh prefix —
+ // resolveUrl only writes where a page was actually built, and the zh
+ // collection is processed after, overwriting the fallback where a real
+ // translation exists.
+ ['docs-apisix-en', ['/docs/apisix', '/zh/docs/apisix']],
Review Comment:
Offering the English collection at the Chinese prefix writes and records an
English fallback for every built Chinese APISIX page, not only pages without a
translation. The Chinese collection then overwrites the file but pushes the
same URL into `written` again, so `/llms.txt` contains both English and Chinese
metadata for translated pages. The release build produced 1,186 unique twin
files but 1,359 index entries, with 173 duplicate URLs. Please key the
collected metadata by URL and let the translated entry replace the fallback;
the parity check should also validate the actual links emitted to `llms.txt`
rather than a Set derived from `written`.
--
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]
