Skip to content

fix(docs): strip .md extension from internal link targets #69

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

Merged
WomB0ComB0 merged 1 commit into from
May 10, 2026
Merged

fix(docs): strip .md extension from internal link targets #69

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
38 changes: 38 additions & 0 deletions automation/source-repo-templates/api-docs.rust.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -407,6 +407,44 @@ jobs:
f.write_text(new, encoding="utf-8")
PY

- name: Strip .md extension from internal link targets
# Mintlify routes URLs without the `.md` extension. A
# markdown link like `[label](./foo.md)` is treated as a
# literal path that 404s in the rendered site, even when
# the target file exists. Drop `.md` (and collapse
# `/index.md` to its parent dir form) so links resolve
# natively. cargo-doc-md generally uses in-page anchors,
# not file links, but README content embedded into landing
# pages routinely carries `.md` suffixes.
working-directory: ${{ env.OUTPUT_DIR }}
run: |
python3 - <<'PY'
import pathlib
import re

link_re = re.compile(r'(?<!\!)\[([^\]]*)\]\(([^)]+)\)')

def strip_md(target: str) -> str:
first_seg = target.split("/", 1)[0]
if ":" in first_seg:
return target
path, _, frag = target.partition("#")
frag = ("#" + frag) if frag else ""
if path.endswith("/index.md"):
path = path[: -len("/index.md")] or "."
elif path.endswith(".md"):
path = path[:-3]
return path + frag

for f in pathlib.Path(".").rglob("*.md"):
text = f.read_text(encoding="utf-8")
def fix(m: re.Match) -> str:
return f"[{m.group(1)}]({strip_md(m.group(2))})"
new = link_re.sub(fix, text)
Comment on lines +425 to +443
Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist Bot May 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The regex-based link stripping logic has several limitations that should be addressed:

  • Code Span Safety: The current implementation does not exclude links within backticks or code blocks (e.g., `[label](file.md)`). This violates the general rule requiring parsing logic to respect CommonMark inline code span rules to avoid modifying content inside code snippets.
  • Links with Titles: Markdown links can include titles (e.g., [label](url.md "title")). The regex ([^)]+) captures the title as part of the target group, causing strip_md to fail to remove the extension because the string ends with a quote instead of .md.
  • Index Inconsistency: path.endswith("/index.md") does not match a link that is exactly index.md. In that case, it falls through to the .md strip logic and becomes index, whereas ./index.md becomes ./. This inconsistency may affect how Mintlify resolves directory-level pages.

Consider using a more robust parsing approach that identifies code spans first and separates the URL from any optional title.

References
  1. When processing Markdown/MDX files to escape curly braces for JSX compatibility, ensure the logic ignores content within inline code spans (backticks) to prevent breaking code snippets.

if new != text:
f.write_text(new, encoding="utf-8")
PY

- name: Escape MDX-special characters outside code regions
# Mintlify parses .md as MDX. Literal `{ ... }` in prose is
# interpreted as a JSX expression; literal `<X>` (e.g.
Expand Down
42 changes: 42 additions & 0 deletions automation/source-repo-templates/api-docs.typescript.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -285,6 +285,48 @@ jobs:
f.write_text(new, encoding="utf-8")
PY

- name: Strip .md extension from internal link targets
# Mintlify routes URLs without the `.md` extension; a
# markdown link like `[label](./foo.md)` is treated as a
# literal path that 404s in the rendered site, even when
# `./foo.md` exists on disk.
#
# `[label](dir/index.md)` collapses to `[label](dir)` so it
# matches the splice's strip-/index registration (the parent
# path resolves to the dir's index landing natively). Plain
# `.md` leaves get the extension dropped; fragments are
# preserved. URL-scheme targets (http://, mailto:, data:)
# are left alone.
working-directory: ${{ env.OUTPUT_DIR }}
run: |
python3 - <<'PY'
import pathlib
import re

link_re = re.compile(r'(?<!\!)\[([^\]]*)\]\(([^)]+)\)')

def strip_md(target: str) -> str:
first_seg = target.split("/", 1)[0]
if ":" in first_seg:
return target
path, _, frag = target.partition("#")
frag = ("#" + frag) if frag else ""
if path.endswith("/index.md"):
path = path[: -len("/index.md")] or "."
elif path.endswith(".md"):
path = path[:-3]
return path + frag

for f in pathlib.Path(".").rglob("*.md"):
text = f.read_text(encoding="utf-8")
def fix(m: re.Match) -> str:
label, target = m.group(1), m.group(2)
return f"[{label}]({strip_md(target)})"
new = link_re.sub(fix, text)
if new != text:
f.write_text(new, encoding="utf-8")
PY
Comment on lines +302 to +328
Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist Bot May 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

This Python script is duplicated from the Rust documentation template. Duplicating complex post-processing logic across multiple workflow files increases maintenance overhead and the risk of inconsistent behavior. Consider extracting this logic into a shared script or a reusable local action to ensure that fixes (such as handling code spans or link titles) are applied consistently across all SDK documentation.


- name: Strip TypeDoc breadcrumb header
# Every typedoc-plugin-markdown page begins with a breadcrumb
# block that links to ../../README.md and similar paths.
Expand Down
8 changes: 4 additions & 4 deletions sdks/typescript/api/analytics/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

## Modules

- [index](./index/index.md)
- [next](./next/index.md)
- [react](./react/index.md)
- [resq](./resq/index.md)
- [index](./index)
- [next](./next)
- [react](./react)
- [resq](./resq)
8 changes: 4 additions & 4 deletions sdks/typescript/api/analytics/index/classes/Analytics.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,13 +18,13 @@ Defined in: [index.ts:111](https://github.com/resq-software/npm/blob/f2ab5fc82f4

#### Get Signature

> **get** **config**(): `Readonly`\<[`AnalyticsConfig`](../interfaces/AnalyticsConfig.md)\> \| `null`
> **get** **config**(): `Readonly`\<[`AnalyticsConfig`](../interfaces/AnalyticsConfig)\> \| `null`

Defined in: [index.ts:116](https://github.com/resq-software/npm/blob/f2ab5fc82f4f501236bfdc25d86881be8e1fb643/packages/analytics/src/index.ts#L116)

##### Returns

`Readonly`\<[`AnalyticsConfig`](../interfaces/AnalyticsConfig.md)\> \| `null`
`Readonly`\<[`AnalyticsConfig`](../interfaces/AnalyticsConfig)\> \| `null`

***

Expand Down Expand Up @@ -74,7 +74,7 @@ Defined in: [index.ts:124](https://github.com/resq-software/npm/blob/f2ab5fc82f4

##### config

[`AnalyticsConfig`](../interfaces/AnalyticsConfig.md)
[`AnalyticsConfig`](../interfaces/AnalyticsConfig)

#### Returns

Expand Down Expand Up @@ -138,7 +138,7 @@ Defined in: [index.ts:166](https://github.com/resq-software/npm/blob/f2ab5fc82f4

##### properties?

`E` *extends* `string` \| `number` ? [`AnalyticsEvents`](../interfaces/AnalyticsEvents.md)\[`E`\] : `Record`\<`string`, `unknown`\>
`E` *extends* `string` \| `number` ? [`AnalyticsEvents`](../interfaces/AnalyticsEvents)\[`E`\] : `Record`\<`string`, `unknown`\>

#### Returns

Expand Down
2 changes: 1 addition & 1 deletion sdks/typescript/api/analytics/index/functions/initAnalytics.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ Defined in: [index.ts:222](https://github.com/resq-software/npm/blob/f2ab5fc82f4

### config

[`AnalyticsConfig`](../interfaces/AnalyticsConfig.md)
[`AnalyticsConfig`](../interfaces/AnalyticsConfig)

## Returns

Expand Down
32 changes: 16 additions & 16 deletions sdks/typescript/api/analytics/index/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,48 +2,48 @@

## Classes

- [Analytics](./classes/Analytics.md)
- [Analytics](./classes/Analytics)

## Interfaces

- [AnalyticsConfig](./interfaces/AnalyticsConfig.md)
- [AnalyticsEvents](./interfaces/AnalyticsEvents.md)
- [GA4ProviderConfig](./interfaces/GA4ProviderConfig.md)
- [PostHogProviderConfig](./interfaces/PostHogProviderConfig.md)
- [AnalyticsConfig](./interfaces/AnalyticsConfig)
- [AnalyticsEvents](./interfaces/AnalyticsEvents)
- [GA4ProviderConfig](./interfaces/GA4ProviderConfig)
- [PostHogProviderConfig](./interfaces/PostHogProviderConfig)

## Variables

- [analytics](./variables/analytics.md)
- [track](./variables/track.md)
- [analytics](./variables/analytics)
- [track](./variables/track)

## Functions

- [identify](./functions/identify.md)
- [inferCookieDomain](./functions/inferCookieDomain.md)
- [initAnalytics](./functions/initAnalytics.md)
- [pageview](./functions/pageview.md)
- [reset](./functions/reset.md)
- [identify](./functions/identify)
- [inferCookieDomain](./functions/inferCookieDomain)
- [initAnalytics](./functions/initAnalytics)
- [pageview](./functions/pageview)
- [reset](./functions/reset)

## References

### GA4\_ID\_PATTERN

Re-exports [GA4_ID_PATTERN](../resq/variables/GA4_ID_PATTERN.md)
Re-exports [GA4_ID_PATTERN](../resq/variables/GA4_ID_PATTERN)

***

### resolveResqCookieDomain

Re-exports [resolveResqCookieDomain](../resq/functions/resolveResqCookieDomain.md)
Re-exports [resolveResqCookieDomain](../resq/functions/resolveResqCookieDomain)

***

### RESQ\_SUBDOMAIN\_ALLOWLIST

Re-exports [RESQ_SUBDOMAIN_ALLOWLIST](../resq/variables/RESQ_SUBDOMAIN_ALLOWLIST.md)
Re-exports [RESQ_SUBDOMAIN_ALLOWLIST](../resq/variables/RESQ_SUBDOMAIN_ALLOWLIST)

***

### sanitizeGa4Id

Re-exports [sanitizeGa4Id](../resq/functions/sanitizeGa4Id.md)
Re-exports [sanitizeGa4Id](../resq/functions/sanitizeGa4Id)
4 changes: 2 additions & 2 deletions sdks/typescript/api/analytics/index/interfaces/AnalyticsConfig.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,14 +30,14 @@ Defined in: [index.ts:54](https://github.com/resq-software/npm/blob/f2ab5fc82f4f

### ga4?

> `optional` **ga4?**: [`GA4ProviderConfig`](./GA4ProviderConfig.md)
> `optional` **ga4?**: [`GA4ProviderConfig`](./GA4ProviderConfig)

Defined in: [index.ts:52](https://github.com/resq-software/npm/blob/f2ab5fc82f4f501236bfdc25d86881be8e1fb643/packages/analytics/src/index.ts#L52)

***

### posthog?

> `optional` **posthog?**: [`PostHogProviderConfig`](./PostHogProviderConfig.md)
> `optional` **posthog?**: [`PostHogProviderConfig`](./PostHogProviderConfig)

Defined in: [index.ts:51](https://github.com/resq-software/npm/blob/f2ab5fc82f4f501236bfdc25d86881be8e1fb643/packages/analytics/src/index.ts#L51)
2 changes: 1 addition & 1 deletion sdks/typescript/api/analytics/index/variables/analytics.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
# Variable: analytics

> `const` **analytics**: [`Analytics`](../classes/Analytics.md)
> `const` **analytics**: [`Analytics`](../classes/Analytics)

Defined in: [index.ts:220](https://github.com/resq-software/npm/blob/f2ab5fc82f4f501236bfdc25d86881be8e1fb643/packages/analytics/src/index.ts#L220)
2 changes: 1 addition & 1 deletion sdks/typescript/api/analytics/index/variables/track.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
# Variable: track

> `const` **track**: [`Analytics`](../classes/Analytics.md)\[`"track"`\]
> `const` **track**: [`Analytics`](../classes/Analytics)\[`"track"`\]

Defined in: [index.ts:224](https://github.com/resq-software/npm/blob/f2ab5fc82f4f501236bfdc25d86881be8e1fb643/packages/analytics/src/index.ts#L224)
4 changes: 2 additions & 2 deletions sdks/typescript/api/analytics/next/functions/ga4Stream.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Function: ga4Stream()

> **ga4Stream**(`measurementId`, `domains?`): [`GA4ProviderConfig`](../../index/interfaces/GA4ProviderConfig.md)
> **ga4Stream**(`measurementId`, `domains?`): [`GA4ProviderConfig`](../../index/interfaces/GA4ProviderConfig)

Defined in: [next/index.ts:74](https://github.com/resq-software/npm/blob/f2ab5fc82f4f501236bfdc25d86881be8e1fb643/packages/analytics/src/next/index.ts#L74)

Expand All @@ -16,4 +16,4 @@ Defined in: [next/index.ts:74](https://github.com/resq-software/npm/blob/f2ab5fc

## Returns

[`GA4ProviderConfig`](../../index/interfaces/GA4ProviderConfig.md)
[`GA4ProviderConfig`](../../index/interfaces/GA4ProviderConfig)
2 changes: 1 addition & 1 deletion sdks/typescript/api/analytics/next/functions/withAnalyticsRewrites.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ Defined in: [next/index.ts:41](https://github.com/resq-software/npm/blob/f2ab5fc

### options?

[`AnalyticsRewriteOptions`](../interfaces/AnalyticsRewriteOptions.md) = `{}`
[`AnalyticsRewriteOptions`](../interfaces/AnalyticsRewriteOptions) = `{}`

## Returns

Expand Down
6 changes: 3 additions & 3 deletions sdks/typescript/api/analytics/next/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,9 @@

## Interfaces

- [AnalyticsRewriteOptions](./interfaces/AnalyticsRewriteOptions.md)
- [AnalyticsRewriteOptions](./interfaces/AnalyticsRewriteOptions)

## Functions

- [ga4Stream](./functions/ga4Stream.md)
- [withAnalyticsRewrites](./functions/withAnalyticsRewrites.md)
- [ga4Stream](./functions/ga4Stream)
- [withAnalyticsRewrites](./functions/withAnalyticsRewrites)
2 changes: 1 addition & 1 deletion sdks/typescript/api/analytics/react/functions/AnalyticsProvider.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ Defined in: [react/index.ts:48](https://github.com/resq-software/npm/blob/f2ab5f

### \_\_namedParameters

[`AnalyticsProviderProps`](../interfaces/AnalyticsProviderProps.md)
[`AnalyticsProviderProps`](../interfaces/AnalyticsProviderProps)

## Returns

Expand Down
4 changes: 2 additions & 2 deletions sdks/typescript/api/analytics/react/functions/useAnalytics.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
# Function: useAnalytics()

> **useAnalytics**(): [`UseAnalyticsReturn`](../interfaces/UseAnalyticsReturn.md)
> **useAnalytics**(): [`UseAnalyticsReturn`](../interfaces/UseAnalyticsReturn)

Defined in: [react/index.ts:81](https://github.com/resq-software/npm/blob/f2ab5fc82f4f501236bfdc25d86881be8e1fb643/packages/analytics/src/react/index.ts#L81)

## Returns

[`UseAnalyticsReturn`](../interfaces/UseAnalyticsReturn.md)
[`UseAnalyticsReturn`](../interfaces/UseAnalyticsReturn)
8 changes: 4 additions & 4 deletions sdks/typescript/api/analytics/react/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,10 @@

## Interfaces

- [AnalyticsProviderProps](./interfaces/AnalyticsProviderProps.md)
- [UseAnalyticsReturn](./interfaces/UseAnalyticsReturn.md)
- [AnalyticsProviderProps](./interfaces/AnalyticsProviderProps)
- [UseAnalyticsReturn](./interfaces/UseAnalyticsReturn)

## Functions

- [AnalyticsProvider](./functions/AnalyticsProvider.md)
- [useAnalytics](./functions/useAnalytics.md)
- [AnalyticsProvider](./functions/AnalyticsProvider)
- [useAnalytics](./functions/useAnalytics)
2 changes: 1 addition & 1 deletion sdks/typescript/api/analytics/react/interfaces/AnalyticsProviderProps.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ Defined in: [react/index.ts:33](https://github.com/resq-software/npm/blob/f2ab5f

### config

> **config**: [`AnalyticsConfig`](../../index/interfaces/AnalyticsConfig.md)
> **config**: [`AnalyticsConfig`](../../index/interfaces/AnalyticsConfig)

Defined in: [react/index.ts:31](https://github.com/resq-software/npm/blob/f2ab5fc82f4f501236bfdc25d86881be8e1fb643/packages/analytics/src/react/index.ts#L31)

Expand Down
4 changes: 2 additions & 2 deletions sdks/typescript/api/analytics/react/interfaces/UseAnalyticsReturn.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ Defined in: [react/index.ts:73](https://github.com/resq-software/npm/blob/f2ab5f

### analytics

> **analytics**: [`Analytics`](../../index/classes/Analytics.md)
> **analytics**: [`Analytics`](../../index/classes/Analytics)

Defined in: [react/index.ts:78](https://github.com/resq-software/npm/blob/f2ab5fc82f4f501236bfdc25d86881be8e1fb643/packages/analytics/src/react/index.ts#L78)

Expand Down Expand Up @@ -84,7 +84,7 @@ Defined in: [react/index.ts:74](https://github.com/resq-software/npm/blob/f2ab5f

##### properties?

`E` *extends* `string` \| `number` ? [`AnalyticsEvents`](../../index/interfaces/AnalyticsEvents.md)\[`E`\] : `Record`\<`string`, `unknown`\>
`E` *extends* `string` \| `number` ? [`AnalyticsEvents`](../../index/interfaces/AnalyticsEvents)\[`E`\] : `Record`\<`string`, `unknown`\>

#### Returns

Expand Down
2 changes: 1 addition & 1 deletion sdks/typescript/api/analytics/resq/functions/sanitizeGa4Id.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

Defined in: [resq.ts:69](https://github.com/resq-software/npm/blob/f2ab5fc82f4f501236bfdc25d86881be8e1fb643/packages/analytics/src/resq.ts#L69)

Validate a GA4 Measurement ID against [GA4\_ID\_PATTERN](../variables/GA4_ID_PATTERN.md).
Validate a GA4 Measurement ID against [GA4\_ID\_PATTERN](../variables/GA4_ID_PATTERN).

## Parameters

Expand Down
8 changes: 4 additions & 4 deletions sdks/typescript/api/analytics/resq/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,10 @@

## Variables

- [GA4\_ID\_PATTERN](./variables/GA4_ID_PATTERN.md)
- [RESQ\_SUBDOMAIN\_ALLOWLIST](./variables/RESQ_SUBDOMAIN_ALLOWLIST.md)
- [GA4\_ID\_PATTERN](./variables/GA4_ID_PATTERN)
- [RESQ\_SUBDOMAIN\_ALLOWLIST](./variables/RESQ_SUBDOMAIN_ALLOWLIST)

## Functions

- [resolveResqCookieDomain](./functions/resolveResqCookieDomain.md)
- [sanitizeGa4Id](./functions/sanitizeGa4Id.md)
- [resolveResqCookieDomain](./functions/resolveResqCookieDomain)
- [sanitizeGa4Id](./functions/sanitizeGa4Id)
4 changes: 2 additions & 2 deletions sdks/typescript/api/decorators/after/after.fn/functions/afterFn.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,13 +24,13 @@ The argument types of the original method

### originalMethod

[`Method`](../../../types/type-aliases/Method.md)\<`D`, `A`\>
[`Method`](../../../types/type-aliases/Method)\<`D`, `A`\>

The method to wrap

### config

[`AfterConfig`](../../after.types/interfaces/AfterConfig.md)\<`any`, `D`\>
[`AfterConfig`](../../after.types/interfaces/AfterConfig)\<`any`, `D`\>

Configuration for the after hook

Expand Down
2 changes: 1 addition & 1 deletion sdks/typescript/api/decorators/after/after.fn/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,4 +2,4 @@

## Functions

- [afterFn](./functions/afterFn.md)
- [afterFn](./functions/afterFn)
Loading
Loading