forked from
npmx.dev/npmx.dev
[READ-ONLY]
a fast, modern browser for the npm registry
fix: resolve relative markdown links to repository blob URLs (#716)
Co-authored-by: Daniel Roe <daniel@roe.dev>
authored by
J.A.R.V.I.S.
Daniel Roe
and committed by
GitHub
b914c043
5cf00f1f
+339
-5
+1
-1
server/api/registry/readme/[...pkg].get.ts
+1
-1
server/api/registry/readme/[...pkg].get.ts
+16
-3
server/utils/readme.ts
+16
-3
server/utils/readme.ts
···
183
183
/**
184
184
* Resolve a relative URL to an absolute URL.
185
185
* If repository info is available, resolve to provider's raw file URLs.
186
-
* Otherwise, fall back to jsdelivr CDN.
186
+
* For markdown files (.md), use blob URLs so they render properly.
187
+
* Otherwise, fall back to jsdelivr CDN (except for .md files which are left unchanged).
187
188
*/
188
189
function resolveUrl(url: string, packageName: string, repoInfo?: RepositoryInfo): string {
189
190
if (!url) return url
···
207
208
// for non-HTTP protocols (javascript:, data:, etc.), don't return, treat as relative
208
209
}
209
210
210
-
// Use provider's raw URL base when repository info is available
211
+
// Check if this is a markdown file link
212
+
const isMarkdownFile = /\.md$/i.test(url.split('?')[0]?.split('#')[0] ?? '')
213
+
214
+
// Use provider's URL base when repository info is available
211
215
// This handles assets that exist in the repo but not in the npm tarball
212
216
if (repoInfo?.rawBaseUrl) {
213
217
// Normalize the relative path (remove leading ./)
···
232
236
}
233
237
}
234
238
235
-
return `${repoInfo.rawBaseUrl}/${relativePath}`
239
+
// For markdown files, use blob URL so they render on the provider's site
240
+
// For other files, use raw URL for direct access
241
+
const baseUrl = isMarkdownFile ? repoInfo.blobBaseUrl : repoInfo.rawBaseUrl
242
+
return `${baseUrl}/${relativePath}`
243
+
}
244
+
245
+
// For markdown files without repo info, leave unchanged (like npm does)
246
+
// This avoids 404s from jsdelivr which doesn't render markdown
247
+
if (isMarkdownFile) {
248
+
return url
236
249
}
237
250
238
251
// Fallback: relative URLs → jsdelivr CDN (may 404 if asset not in npm tarball)
+176
test/unit/server/utils/readme.spec.ts
+176
test/unit/server/utils/readme.spec.ts
···
1
+
import type { RepositoryInfo } from '#shared/utils/git-providers'
1
2
import { describe, expect, it, vi, beforeAll } from 'vitest'
2
3
3
4
// Mock the global Nuxt auto-import before importing the module
···
13
14
14
15
// Import after mock is set up
15
16
const { renderReadmeHtml } = await import('../../../../server/utils/readme')
17
+
18
+
// Helper to create mock repository info
19
+
function createRepoInfo(overrides?: Partial<RepositoryInfo>): RepositoryInfo {
20
+
return {
21
+
provider: 'github',
22
+
owner: 'test-owner',
23
+
repo: 'test-repo',
24
+
rawBaseUrl: 'https://raw.githubusercontent.com/test-owner/test-repo/HEAD',
25
+
blobBaseUrl: 'https://github.com/test-owner/test-repo/blob/HEAD',
26
+
...overrides,
27
+
}
28
+
}
16
29
17
30
describe('Playground Link Extraction', () => {
18
31
describe('StackBlitz', () => {
···
131
144
})
132
145
})
133
146
})
147
+
148
+
describe('Markdown File URL Resolution', () => {
149
+
describe('with repository info', () => {
150
+
it('resolves relative .md links to blob URL for rendered viewing', async () => {
151
+
const repoInfo = createRepoInfo()
152
+
const markdown = `[Contributing](./CONTRIBUTING.md)`
153
+
const result = await renderReadmeHtml(markdown, 'test-pkg', repoInfo)
154
+
155
+
expect(result.html).toContain(
156
+
'href="https://github.com/test-owner/test-repo/blob/HEAD/CONTRIBUTING.md"',
157
+
)
158
+
})
159
+
160
+
it('resolves relative .MD links (uppercase) to blob URL', async () => {
161
+
const repoInfo = createRepoInfo()
162
+
const markdown = `[Guide](./GUIDE.MD)`
163
+
const result = await renderReadmeHtml(markdown, 'test-pkg', repoInfo)
164
+
165
+
expect(result.html).toContain(
166
+
'href="https://github.com/test-owner/test-repo/blob/HEAD/GUIDE.MD"',
167
+
)
168
+
})
169
+
170
+
it('resolves nested relative .md links to blob URL', async () => {
171
+
const repoInfo = createRepoInfo()
172
+
const markdown = `[API Docs](./docs/api/reference.md)`
173
+
const result = await renderReadmeHtml(markdown, 'test-pkg', repoInfo)
174
+
175
+
expect(result.html).toContain(
176
+
'href="https://github.com/test-owner/test-repo/blob/HEAD/docs/api/reference.md"',
177
+
)
178
+
})
179
+
180
+
it('resolves relative .md links with query strings to blob URL', async () => {
181
+
const repoInfo = createRepoInfo()
182
+
const markdown = `[FAQ](./FAQ.md?ref=main)`
183
+
const result = await renderReadmeHtml(markdown, 'test-pkg', repoInfo)
184
+
185
+
expect(result.html).toContain(
186
+
'href="https://github.com/test-owner/test-repo/blob/HEAD/FAQ.md?ref=main"',
187
+
)
188
+
})
189
+
190
+
it('resolves relative .md links with anchors to blob URL', async () => {
191
+
const repoInfo = createRepoInfo()
192
+
const markdown = `[Install Section](./CONTRIBUTING.md#installation)`
193
+
const result = await renderReadmeHtml(markdown, 'test-pkg', repoInfo)
194
+
195
+
expect(result.html).toContain(
196
+
'href="https://github.com/test-owner/test-repo/blob/HEAD/CONTRIBUTING.md#installation"',
197
+
)
198
+
})
199
+
200
+
it('resolves non-.md files to raw URL (not blob)', async () => {
201
+
const repoInfo = createRepoInfo()
202
+
const markdown = `[Image](./assets/logo.png)`
203
+
const result = await renderReadmeHtml(markdown, 'test-pkg', repoInfo)
204
+
205
+
expect(result.html).toContain(
206
+
'href="https://raw.githubusercontent.com/test-owner/test-repo/HEAD/assets/logo.png"',
207
+
)
208
+
})
209
+
210
+
it('handles monorepo directory for .md links', async () => {
211
+
const repoInfo = createRepoInfo({
212
+
directory: 'packages/core',
213
+
})
214
+
const markdown = `[Changelog](./CHANGELOG.md)`
215
+
const result = await renderReadmeHtml(markdown, 'test-pkg', repoInfo)
216
+
217
+
expect(result.html).toContain(
218
+
'href="https://github.com/test-owner/test-repo/blob/HEAD/packages/core/CHANGELOG.md"',
219
+
)
220
+
})
221
+
222
+
it('handles parent directory navigation for .md links', async () => {
223
+
const repoInfo = createRepoInfo({
224
+
directory: 'packages/core',
225
+
})
226
+
const markdown = `[Root Contributing](../../CONTRIBUTING.md)`
227
+
const result = await renderReadmeHtml(markdown, 'test-pkg', repoInfo)
228
+
229
+
expect(result.html).toContain(
230
+
'href="https://github.com/test-owner/test-repo/blob/HEAD/CONTRIBUTING.md"',
231
+
)
232
+
})
233
+
})
234
+
235
+
describe('without repository info', () => {
236
+
it('leaves relative .md links unchanged (no jsdelivr fallback)', async () => {
237
+
const markdown = `[Contributing](./CONTRIBUTING.md)`
238
+
const result = await renderReadmeHtml(markdown, 'test-pkg')
239
+
240
+
// Should remain unchanged, not converted to jsdelivr
241
+
expect(result.html).toContain('href="./CONTRIBUTING.md"')
242
+
})
243
+
244
+
it('resolves non-.md files to jsdelivr CDN', async () => {
245
+
const markdown = `[Schema](./schema.json)`
246
+
const result = await renderReadmeHtml(markdown, 'test-pkg')
247
+
248
+
expect(result.html).toContain('href="https://cdn.jsdelivr.net/npm/test-pkg/schema.json"')
249
+
})
250
+
})
251
+
252
+
describe('absolute URLs', () => {
253
+
it('leaves absolute .md URLs unchanged', async () => {
254
+
const repoInfo = createRepoInfo()
255
+
const markdown = `[External Guide](https://example.com/guide.md)`
256
+
const result = await renderReadmeHtml(markdown, 'test-pkg', repoInfo)
257
+
258
+
expect(result.html).toContain('href="https://example.com/guide.md"')
259
+
})
260
+
261
+
it('leaves absolute non-.md URLs unchanged', async () => {
262
+
const repoInfo = createRepoInfo()
263
+
const markdown = `[Docs](https://docs.example.com/)`
264
+
const result = await renderReadmeHtml(markdown, 'test-pkg', repoInfo)
265
+
266
+
expect(result.html).toContain('href="https://docs.example.com/"')
267
+
})
268
+
})
269
+
270
+
describe('anchor links', () => {
271
+
it('prefixes anchor links with user-content-', async () => {
272
+
const markdown = `[Jump to section](#installation)`
273
+
const result = await renderReadmeHtml(markdown, 'test-pkg')
274
+
275
+
expect(result.html).toContain('href="#user-content-installation"')
276
+
})
277
+
})
278
+
279
+
describe('different git providers', () => {
280
+
it('uses correct blob URL format for GitLab', async () => {
281
+
const repoInfo = createRepoInfo({
282
+
provider: 'gitlab',
283
+
host: 'gitlab.com',
284
+
rawBaseUrl: 'https://gitlab.com/owner/repo/-/raw/HEAD',
285
+
blobBaseUrl: 'https://gitlab.com/owner/repo/-/blob/HEAD',
286
+
})
287
+
const markdown = `[Docs](./docs/guide.md)`
288
+
const result = await renderReadmeHtml(markdown, 'test-pkg', repoInfo)
289
+
290
+
expect(result.html).toContain(
291
+
'href="https://gitlab.com/owner/repo/-/blob/HEAD/docs/guide.md"',
292
+
)
293
+
})
294
+
295
+
it('uses correct blob URL format for Bitbucket', async () => {
296
+
const repoInfo = createRepoInfo({
297
+
provider: 'bitbucket',
298
+
rawBaseUrl: 'https://bitbucket.org/owner/repo/raw/HEAD',
299
+
blobBaseUrl: 'https://bitbucket.org/owner/repo/src/HEAD',
300
+
})
301
+
const markdown = `[Readme](./other/README.md)`
302
+
const result = await renderReadmeHtml(markdown, 'test-pkg', repoInfo)
303
+
304
+
expect(result.html).toContain(
305
+
'href="https://bitbucket.org/owner/repo/src/HEAD/other/README.md"',
306
+
)
307
+
})
308
+
})
309
+
})