Skip to content

fix: fix DM archive doc URL resolution #701

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
qiancai wants to merge 4 commits into
base: master
Choose a base branch
from
Open

fix: fix DM archive doc URL resolution #701

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
c0dfed4
fix dm archive url resolution
qiancai May 6, 2026
9e2ecd0
Merge branch 'fix-dm-archive-urls' into fix-dm-archive-doc-urls
qiancai May 13, 2026
b53d763
update config.ts
qiancai May 13, 2026
f76c889
fix: show the version selection drop-down list for DM archived docs
qiancai May 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 42 additions & 0 deletions gatsby/link-resolver/__tests__/link-resolver.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -536,6 +536,48 @@ describe("resolveMarkdownLink", () => {
expect(result).toBe("/tidb-in-kubernetes/stable/deploy");
});

it("should resolve links from tidb-data-migration pages", () => {
const result = resolveMarkdownLink(
"/dm-overview",
"/zh/tidb-data-migration/v5.3/quick-start-with-dm"
);
expect(result).toBe("/zh/tidb-data-migration/v5.3/dm-overview");
});

it("should resolve links from tidb-data-migration pages without language prefix", () => {
const result = resolveMarkdownLink(
"/quick-start-with-dm",
"/tidb-data-migration/v5.3/dm-overview"
);
expect(result).toBe("/tidb-data-migration/v5.3/quick-start-with-dm");
});

it("should resolve nested links from tidb-data-migration pages using flattened doc URLs", () => {
const result = resolveMarkdownLink(
"/releases/2.0.7",
"/zh/tidb-data-migration/v2.0/TOC"
);
expect(result).toBe("/zh/tidb-data-migration/v2.0/2.0.7");
});

it("should preserve hash for tidb-data-migration links", () => {
const result = resolveMarkdownLink(
"/key-features#table-routing",
"/zh/tidb-data-migration/v2.0/overview"
);
expect(result).toBe(
"/zh/tidb-data-migration/v2.0/key-features#table-routing"
);
});

it("should resolve _index links from tidb-data-migration pages", () => {
const result = resolveMarkdownLink(
"/reference/_index",
"/en/tidb-data-migration/v5.3/TOC"
);
expect(result).toBe("/tidb-data-migration/v5.3/reference");
});

it("should not match non-tidb repo pages (pathConditions check)", () => {
const result = resolveMarkdownLink(
"/upgrade/upgrade-tidb-using-tiup",
Expand Down
10 changes: 5 additions & 5 deletions gatsby/link-resolver/config.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -88,21 +88,21 @@ export const defaultLinkResolverConfig: LinkResolverConfig = {
linkPattern: "/{...any}/{docname}",
targetPattern: "/{lang}/tidb/stable/{docname}",
},
// Rule 4: tidb with branch pages (path-based mapping)
// Current page: /{lang}/tidb/{branch}/{...any} (branch is already aliased, e.g., "stable", "v8.5")
// Link: /{...any}/{docname} -> /{lang}/tidb/{branch}/{docname}
// Rule 4: versioned docs with branch pages (path-based mapping)
// Current page: /{lang}/{repo}/{branch}/{...any} (branch is already aliased, e.g., "stable", "v8.5")
// Link: /{...any}/{docname} -> /{lang}/{repo}/{branch}/{docname}
{
pathPattern: "/{lang}/{repo}/{branch}/{...any}",
pathConditions: {
repo: ["tidb", "tidb-in-kubernetes"],
repo: ["tidb", "tidb-in-kubernetes", "tidb-data-migration"],
},
linkPattern: "/{...folders}/_index",
targetPattern: "/{lang}/{repo}/{branch}/{folders}",
},
{
pathPattern: "/{lang}/{repo}/{branch}/{...any}",
pathConditions: {
repo: ["tidb", "tidb-in-kubernetes"],
repo: ["tidb", "tidb-in-kubernetes", "tidb-data-migration"],
},
linkPattern: "/{...any}/{docname}",
targetPattern: "/{lang}/{repo}/{branch}/{docname}",
Expand Down
91 changes: 91 additions & 0 deletions gatsby/url-resolver/__tests__/url-resolver.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -214,6 +214,42 @@ describe("calculateFileUrl", () => {
expect(url).toBe("/en/tidb/dev/page/");
});

it("should resolve tidb-data-migration _index with release branch alias", () => {
const absolutePath = path.join(
sourceBasePath,
"zh/tidb-data-migration/release-2.0/_index.md"
);
const url = calculateFileUrlWithConfig(absolutePath, testConfig);
expect(url).toBe("/zh/tidb-data-migration/v2.0");
});

it("should resolve tidb-data-migration pages with release branch alias", () => {
const absolutePath = path.join(
sourceBasePath,
"zh/tidb-data-migration/release-2.0/overview.md"
);
const url = calculateFileUrlWithConfig(absolutePath, testConfig);
expect(url).toBe("/zh/tidb-data-migration/v2.0/overview/");
});

it("should resolve tidb-data-migration v1.0 pages with release branch alias", () => {
const absolutePath = path.join(
sourceBasePath,
"zh/tidb-data-migration/release-1.0/overview.md"
);
const url = calculateFileUrlWithConfig(absolutePath, testConfig);
expect(url).toBe("/zh/tidb-data-migration/v1.0/overview/");
});

it("should resolve tidb-data-migration nested _index with folders", () => {
const absolutePath = path.join(
sourceBasePath,
"zh/tidb-data-migration/release-2.0/releases/_index.md"
);
const url = calculateFileUrlWithConfig(absolutePath, testConfig);
expect(url).toBe("/zh/tidb-data-migration/v2.0/releases");
});

it("should resolve api folder", () => {
const absolutePath = path.join(
sourceBasePath,
Expand Down Expand Up @@ -469,6 +505,61 @@ describe("calculateFileUrl with defaultLanguage: 'en'", () => {
// release-8.5 -> stable via branch-alias-tidb (exact match takes precedence)
expect(url).toBe("/tidb/stable/alert-rules");
});

it("should omit /en/ prefix for English tidb-data-migration files", () => {
const absolutePath = path.join(
sourceBasePath,
"en/tidb-data-migration/release-5.3/dm-overview.md"
);
const url = calculateFileUrlWithConfig(
absolutePath,
configWithDefaultLang,
true
);
expect(url).toBe("/tidb-data-migration/v5.3/dm-overview");
});

it("should omit /en/ prefix for English tidb-data-migration release indexes", () => {
const cases = [
["release-5.3", "/tidb-data-migration/v5.3"],
["release-2.0", "/tidb-data-migration/v2.0"],
["release-1.0", "/tidb-data-migration/v1.0"],
];

for (const [branch, expected] of cases) {
const absolutePath = path.join(
sourceBasePath,
`en/tidb-data-migration/${branch}/_index.md`
);
const url = calculateFileUrlWithConfig(
absolutePath,
configWithDefaultLang,
true
);
expect(url).toBe(expected);
}
});

it("should keep /zh/ prefix for Chinese tidb-data-migration release indexes", () => {
const cases = [
["release-5.3", "/zh/tidb-data-migration/v5.3"],
["release-2.0", "/zh/tidb-data-migration/v2.0"],
["release-1.0", "/zh/tidb-data-migration/v1.0"],
];

for (const [branch, expected] of cases) {
const absolutePath = path.join(
sourceBasePath,
`zh/tidb-data-migration/${branch}/_index.md`
);
const url = calculateFileUrlWithConfig(
absolutePath,
configWithDefaultLang,
true
);
expect(url).toBe(expected);
}
});
});

describe("calculateFileUrl with slug format (relative path)", () => {
Expand Down
32 changes: 32 additions & 0 deletions gatsby/url-resolver/config.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -123,6 +123,28 @@ export const defaultUrlResolverConfig: UrlResolverConfig = {
ignoreIf: ["_index", "_docHome"],
},
},
// tidb-data-migration index pages with folders (avoid URL collision)
Comment thread
qiancai marked this conversation as resolved.
{
sourcePattern:
"/{lang}/tidb-data-migration/{branch}/{...folders}/{filename}",
targetPattern:
"/{lang}/tidb-data-migration/{branch:branch-alias-tidb-data-migration}/{folders}",
conditions: { filename: ["_index"] },
filenameTransform: {
ignoreIf: ["_index"],
},
},
// tidb-data-migration with branch and optional folders
// /en/tidb-data-migration/release-5.3/{...folders}/{filename} -> /en/tidb-data-migration/v5.3/{filename}
{
sourcePattern:
"/{lang}/tidb-data-migration/{branch}/{...folders}/{filename}",
targetPattern:
"/{lang}/tidb-data-migration/{branch:branch-alias-tidb-data-migration}/{filename}",
filenameTransform: {
ignoreIf: ["_index", "_docHome"],
},
},
// Fallback: /{lang}/{repo}/{...any}/{filename} -> /{lang}/{repo}/{filename}
{
sourcePattern: "/{lang}/{repo}/{...any}/{filename}",
Expand Down Expand Up @@ -164,5 +186,15 @@ export const defaultUrlResolverConfig: UrlResolverConfig = {
"release-*": "v*",
},
},
// Branch alias for tidb-data-migration: used in {branch:branch-alias-tidb-data-migration}
"branch-alias-tidb-data-migration": {
mappings: {
// Wildcard pattern: release-* -> v*
// Examples:
// release-5.3 -> v5.3
// release-2.0 -> v2.0
"release-*": "v*",
},
},
},
};
21 changes: 17 additions & 4 deletions src/components/Layout/LeftNav/LeftNav.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@ import {
BuildType,
TOCNamespace,
CloudPlan,
Repo,
} from "shared/interface";
import { NavItemConfig } from "../Header/HeaderNavConfigType";
import LinkComponent from "components/Link";
Expand All @@ -41,6 +42,20 @@ interface LeftNavProps {
namespace?: TOCNamespace;
}

function shouldShowVersionSelect(
namespace: TOCNamespace | undefined,
repo: Repo,
buildType: BuildType | undefined
) {
// DM has no active docs namespace on the main site; only its archived pages
// need the version selector.
return (
namespace === TOCNamespace.TiDB ||
namespace === TOCNamespace.TiDBInKubernetes ||
(buildType === "archive" && repo === Repo.dm)
);
}

export function LeftNavDesktop(props: LeftNavProps) {
const {
data,
Expand Down Expand Up @@ -127,8 +142,7 @@ export function LeftNavDesktop(props: LeftNavProps) {
</Box>
)}

{(namespace === TOCNamespace.TiDB ||
namespace === TOCNamespace.TiDBInKubernetes) && (
{shouldShowVersionSelect(namespace, pathConfig.repo, buildType) && (
<Box marginTop={1}>
<VersionSelect
name={name}
Expand Down Expand Up @@ -197,8 +211,7 @@ export function LeftNavMobile(props: LeftNavProps) {
paddingLeft: "1.25rem",
}}
/>
{(namespace === TOCNamespace.TiDB ||
namespace === TOCNamespace.TiDBInKubernetes) && (
{shouldShowVersionSelect(namespace, pathConfig.repo, buildType) && (
<NativeVersionSelect
name={name}
pathConfig={pathConfig}
Expand Down
39 changes: 27 additions & 12 deletions src/components/Layout/VersionSelect/VersionSelect.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,22 @@ function renderVersion(
);
}

function getArchivedVersions(pathConfig: PathConfig): (string | null)[] {
const repoCfg = CONFIG.docs[pathConfig.repo] as {
archived?: string[];
};
return repoCfg.archived || [];
}

function getVersionOptions(
pathConfig: PathConfig,
isArchive: boolean
): (string | null)[] {
return isArchive
? getArchivedVersions(pathConfig)
: AllVersion[pathConfig.repo][pathConfig.locale];
}

const VersionItems = (props: {
versions: (string | null)[];
availIn: string[];
Expand Down Expand Up @@ -200,11 +216,6 @@ const VersionItemsArchived = (props: {
}) => {
const { versions, availIn, pathConfig, name } = props;

const repoCfg = CONFIG.docs[pathConfig.repo] as {
[key: string]: any;
};
const archiveList = (repoCfg?.archived as string[]) || [];

return (
<>
<FormLabel
Expand All @@ -217,7 +228,7 @@ const VersionItemsArchived = (props: {
>
Archive
</FormLabel>
{archiveList.map((version) => (
{versions.map((version) => (
<MenuItem
disableRipple
key={`menu-${version}`}
Expand Down Expand Up @@ -257,6 +268,8 @@ export default function VersionSelect(props: VersionSelectProps) {
const [open, setOpen] = React.useState<boolean>(false);
const handleClick = () => setOpen(true);
const handleClose = () => setOpen(false);
const isArchive = buildType === "archive";
const versionOptions = getVersionOptions(pathConfig, isArchive);

return (
<>
Expand All @@ -275,7 +288,7 @@ export default function VersionSelect(props: VersionSelectProps) {
fontWeight: 700,
}}
>
{buildType === "archive"
{isArchive
? renderVersion(pathConfig.version, pathConfig, true)
: renderVersion(pathConfig.version, pathConfig)}
</Typography>
Expand All @@ -290,9 +303,9 @@ export default function VersionSelect(props: VersionSelectProps) {
"aria-labelledby": "version-select-button",
}}
>
{buildType === "archive" ? (
{isArchive ? (
<VersionItemsArchived
versions={AllVersion[pathConfig.repo][pathConfig.locale]}
versions={versionOptions}
availIn={availIn}
pathConfig={pathConfig}
name={name}
Expand Down Expand Up @@ -332,6 +345,8 @@ export function NativeVersionSelect(props: VersionSelectProps) {
const { name, pathConfig, availIn, buildType } = props;

const { navigate: i18nNavigate, t, language } = useI18next();
const isArchive = buildType === "archive";
const versionOptions = getVersionOptions(pathConfig, isArchive);

const handleChange = (event: { target: { value: string } }) => {
if (event.target.value === "archive") {
Expand All @@ -353,16 +368,16 @@ export function NativeVersionSelect(props: VersionSelectProps) {
onChange={handleChange}
input={<BootstrapInput />}
>
{AllVersion[pathConfig.repo][pathConfig.locale].map((version) => (
{versionOptions.map((version) => (
<option
key={`${version}`}
value={`${version}`}
disabled={!availIn.includes(version || "")}
>
{renderVersion(version, pathConfig)}
{renderVersion(version, pathConfig, isArchive)}
</option>
))}
{buildType !== "archive" && (
{!isArchive && (
<option key="archive" value="archive">
{t("navbar.archive-label")}
</option>
Expand Down
Loading