upcontent 0.1.0 → 0.1.2

package/package.json

@@ -1,18 +1,31 @@
 {
   "name": "upcontent",
   "type": "module",
-  "version": "0.1.0",
+  "version": "0.1.2",
+  "packageManager": "pnpm@10.20.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lumamontes/upcontent.git"
+  },
   "bin": {
     "upcontent": "scripts/upcontent-cli.mjs"
   },
+  "scripts": {
+    "dev": "astro dev",
+    "build": "astro build",
+    "check": "astro check",
+    "test": "vitest run"
+  },
   "dependencies": {
     "@astrojs/markdown-remark": "^7.3.1",
+    "@astrojs/sitemap": "^3.7.4",
     "@astrojs/starlight": "^0.42.1",
     "@fontsource/poppins": "^5.3.0",
     "astro": "^7.3.3",
     "js-yaml": "^4.3.2",
     "mermaid": "^11.0.0",
     "papaparse": "^5.7.0",
+    "unified": "^11.0.5",
     "unist-util-visit": "^5.0.0",
     "zod": "^3.0.0"
   },
@@ -24,13 +37,6 @@
     "remark-parse": "^11.0.0",
     "remark-rehype": "^11.1.2",
     "typescript": "^5.0.0",
-    "unified": "^11.0.5",
     "vitest": "^2.0.0"
-  },
-  "scripts": {
-    "dev": "astro dev",
-    "build": "astro build",
-    "check": "astro check",
-    "test": "vitest run"
   }
-}
+}

package/scripts/upcontent-cli.mjs

@@ -56,7 +56,7 @@ on:
 
 jobs:
   publish:
-     uses: lumamontes/upcontent/.github/workflows/reusable-pages.yml@main
+    uses: lumamontes/upcontent/.github/workflows/reusable-pages.yml@main
     permissions:
       contents: read
       pages: write
@@ -103,9 +103,7 @@ else if (command === 'dev') {
   process.exitCode = run('make', ['dev', `CONTENT_PATH=${root}`]) ? 0 : 1
 }
 else if (command === 'check') {
-  const passed = run('pnpm', ['test'])
-    && run('pnpm', ['check'])
-    && run('make', ['build', `CONTENT_PATH=${root}`])
+  const passed = run('make', ['build', `CONTENT_PATH=${root}`])
   process.exitCode = passed ? 0 : 1
 }
 else {

package/scripts/verify-external-build.mjs

@@ -1,6 +1,6 @@
 import { existsSync, readdirSync, readFileSync } from 'node:fs'
 
-const html = readFileSync('dist/readme/index.html', 'utf8')
+const html = readFileSync('dist/index.html', 'utf8')
 const required = [
   'External Consumer',
   'https://github.com/example/external-consumer',
@@ -13,7 +13,15 @@ for (const value of required) {
 
 if (!existsSync('dist/upcontent-assets/favicon.svg')) throw new Error('External consumer favicon was not copied')
 if (!html.includes('alt="External Consumer"')) throw new Error('External consumer logo was not rendered')
+if (!html.includes('application/ld+json')) throw new Error('External consumer JSON-LD metadata is missing')
+if (!existsSync('dist/robots.txt')) throw new Error('External consumer robots.txt is missing')
+if (!existsSync('dist/sitemap-index.xml')) throw new Error('External consumer sitemap is missing')
+if (!readFileSync('dist/noindex/index.html', 'utf8').includes('noindex, nofollow')) throw new Error('External consumer noindex page is not marked noindex')
+const sitemap = readFileSync('dist/sitemap-0.xml', 'utf8')
+if (!sitemap.includes('<loc>https://docs.example.com/</loc>')) throw new Error('External consumer root route is missing from sitemap')
+if (sitemap.includes('/noindex/')) throw new Error('External consumer noindex page leaked into sitemap')
 if (existsSync('dist/forbidden/index.html')) throw new Error('External consumer blocklist leaked forbidden.md')
+if (existsSync('dist/assets/readme')) throw new Error('Golden README assets leaked into external consumer build')
 if (existsSync('dist/upcontent-renderer/readme/index.html')) {
   throw new Error('External consumer build leaked renderer checkout content')
 }

package/scripts/verify-golden-build.mjs

@@ -0,0 +1,13 @@
+import { existsSync, readFileSync } from 'node:fs'
+
+const htmlPath = existsSync('dist/readme/index.html') ? 'dist/readme/index.html' : 'dist/index.html'
+const html = readFileSync(htmlPath, 'utf8')
+const requiredAssets = ['assets/readme/portal-home.png', 'assets/readme/portal-showcase.png']
+
+for (const asset of requiredAssets) {
+  if (!existsSync(`dist/${asset}`)) throw new Error(`Golden build is missing: dist/${asset}`)
+  if (existsSync('dist/readme/index.html') && !existsSync(`dist/readme/${asset}`)) {
+    throw new Error(`Golden build is missing README route asset: dist/readme/${asset}`)
+  }
+  if (!html.includes(asset)) throw new Error(`Golden build does not reference: ${asset}`)
+}

package/src/components/MermaidLoader.astro

@@ -2,14 +2,21 @@
 ---
 
 <script>
-  import mermaid from 'mermaid'
   import { renderMermaidDiagram } from '../lib/mermaid-render'
 
   function mermaidTheme() {
     return document.documentElement.dataset.theme === 'dark' ? 'dark' : 'default'
   }
 
-  mermaid.initialize({ startOnLoad: false, theme: mermaidTheme() })
+  let mermaidPromise: Promise<typeof import('mermaid').default> | undefined
+
+  function loadMermaid() {
+    mermaidPromise ??= import('mermaid').then(({ default: mermaid }) => {
+      mermaid.initialize({ startOnLoad: false, theme: mermaidTheme() })
+      return mermaid
+    })
+    return mermaidPromise
+  }
 
   let scale = 1
   let translateX = 0
@@ -105,6 +112,9 @@
 
   async function processDiagrams() {
     const nodes = Array.from(document.querySelectorAll<HTMLElement>('div.mermaid'))
+    if (nodes.length === 0) return
+
+    const mermaid = await loadMermaid()
     for (const node of nodes) {
       // <br/> inside a div becomes a DOM element before textContent reads it — não deveria
       // acontecer (remarkMermaid já normaliza), mas o replace aqui é defensivo.
@@ -162,8 +172,12 @@
   }
 
   async function rerenderExistingDiagrams() {
+    const containers = Array.from(document.querySelectorAll<HTMLElement>('[data-mermaid-source]'))
+    if (containers.length === 0) return
+
+    const mermaid = await loadMermaid()
     mermaid.initialize({ startOnLoad: false, theme: mermaidTheme() })
-    for (const container of document.querySelectorAll<HTMLElement>('[data-mermaid-source]')) {
+    for (const container of containers) {
       const source = container.dataset.mermaidSource
       if (!source) continue
       const result = await renderMermaidDiagram(mermaid, source)

package/src/content/i18n/en.json

@@ -0,0 +1 @@
+{}

package/src/content.config.test.ts

@@ -6,7 +6,7 @@ vi.mock('node:fs', () => ({
 }))
 
 import * as fs from 'node:fs'
-import { domainFieldsSchema, isBlocked, resolveTitle, toRelativeDocPath } from './content.config'
+import { domainFieldsSchema, isBlocked, resolveTitle, toCollectionId, toRelativeDocPath } from './content.config'
 import { _resetPortalConfigCache } from './lib/portal-config'
 
 beforeEach(() => {
@@ -28,6 +28,28 @@ describe('domainFieldsSchema', () => {
     expect(result.success).toBe(true)
   })
 
+  it('aceita SEO por página com canonical absoluto e noindex', () => {
+    const result = domainFieldsSchema.safeParse({
+      canonical: 'https://docs.example.com/guides/seo/',
+      image: 'https://docs.example.com/social-card.png',
+      noindex: true,
+    })
+
+    expect(result.success).toBe(true)
+  })
+
+  it('rejeita canonical relativo', () => {
+    const result = domainFieldsSchema.safeParse({ canonical: '/guides/seo/' })
+
+    expect(result.success).toBe(false)
+  })
+
+  it('rejeita canonical com esquema que não é HTTP(S)', () => {
+    const result = domainFieldsSchema.safeParse({ canonical: 'mailto:docs@example.com' })
+
+    expect(result.success).toBe(false)
+  })
+
   it('aceita created/updated como objeto Date (YAML parseia datas automaticamente)', () => {
     const result = domainFieldsSchema.safeParse({
       created: new Date('2026-08-07'),
@@ -72,6 +94,12 @@ describe('resolveTitle', () => {
     expect(data.title).toBe('Trd Backend')
   })
 
+  it('remove todas as extensões Markdown suportadas no título', () => {
+    const data: Record<string, unknown> = {}
+    resolveTitle('guides/legacy.markdown', data)
+    expect(data.title).toBe('Legacy')
+  })
+
   it('remove prefixo numérico do filename antes de converter', () => {
     const data: Record<string, unknown> = {}
     resolveTitle('docs/adr/0001-self-hosted.md', data)
@@ -161,3 +189,26 @@ describe('toRelativeDocPath', () => {
     expect(toRelativeDocPath('RULES.md')).toBe('RULES.md')
   })
 })
+
+describe('toCollectionId', () => {
+  it('maps the root README to the Starlight homepage id', () => {
+    expect(toCollectionId('README.md')).toBe('index')
+  })
+
+  it('keeps README separate when root index.md is the homepage', () => {
+    expect(toCollectionId('index.md', 'index')).toBe('index')
+    expect(toCollectionId('README.md', 'index')).toBe('readme')
+  })
+
+  it('normalizes document ids while preserving nested routes', () => {
+    expect(toCollectionId('Guides/Getting-Started.mdx')).toBe('guides/getting-started')
+  })
+
+  it('normalizes alternative Markdown extensions', () => {
+    expect(toCollectionId('Guides/Legacy.markdown')).toBe('guides/legacy')
+  })
+
+  it('normalizes nested index documents to their directory route', () => {
+    expect(toCollectionId('customization/index.md')).toBe('customization')
+  })
+})

package/src/content.config.ts

@@ -2,10 +2,13 @@ import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { defineCollection } from 'astro:content'
 import { z } from 'astro/zod'
-import { docsSchema } from '@astrojs/starlight/schema'
+import { docsSchema, i18nSchema } from '@astrojs/starlight/schema'
+import { i18nLoader } from '@astrojs/starlight/loaders'
 import { glob } from 'astro/loaders'
 import type { Loader, LoaderContext } from 'astro/loaders'
 import { getBlocklist, isBlocked, toRelativeDocPath, toTitleCase } from './lib/content-blocklist'
+import { hasRootIndex } from './lib/homepage'
+import { MARKDOWN_EXTENSION, stripMarkdownExtension } from './lib/markdown'
 import { getPortalConfig } from './lib/portal-config'
 
 export { getBlocklist, isBlocked, toRelativeDocPath }
@@ -16,6 +19,16 @@ export { getBlocklist, isBlocked, toRelativeDocPath }
 // SchemaContext (o título obrigatório do Starlight é resolvido pelo loader,
 // não pelo schema — ver resolveTitle()).
 export const domainFieldsSchema = z.object({
+  canonical: z.string().refine(value => {
+    try {
+      const url = new URL(value)
+      return (url.protocol === 'http:' || url.protocol === 'https:') && !url.username && !url.password
+    } catch {
+      return false
+    }
+  }, 'canonical must be an absolute HTTP(S) URL').optional(),
+  image: z.string().optional(),
+  noindex: z.boolean().optional(),
   type: z.string().optional(),
   status: z.string().optional(),
   created: z.string().or(z.date().transform(d => d.toISOString().split('T')[0])).optional(),
@@ -48,10 +61,17 @@ export function resolveTitle(relativeFilePath: string, data: Record<string, unkn
   }
 
   const filename = relativeFilePath.split('/').pop() ?? relativeFilePath
-  const withoutExt = filename.replace(/\.mdx?$/i, '')
+  const withoutExt = filename.replace(MARKDOWN_EXTENSION, '')
   data.title = toTitleCase(withoutExt)
 }
 
+export function toCollectionId(relativeFilePath: string, homepage: 'index' | 'readme' = 'readme'): string {
+  const normalized = stripMarkdownExtension(relativeFilePath.split(path.sep).join('/')).toLowerCase()
+  if (normalized === homepage) return 'index'
+  if (normalized === 'readme') return 'readme'
+  return normalized.endsWith('/index') ? normalized.slice(0, -'/index'.length) : normalized
+}
+
 function toCaseInsensitiveGlob(value: string): string {
   return value.replace(/[A-Za-z]/g, character => `[${character.toLowerCase()}${character.toUpperCase()}]`)
 }
@@ -63,6 +83,7 @@ function portalDocsLoader(): Loader {
     name: 'portal-docs-loader',
     async load(context: LoaderContext) {
       const docsBasePath = fileURLToPath(new URL('src/content/docs/', context.config.root))
+      const homepage = hasRootIndex(docsBasePath) ? 'index' : 'readme'
       const patterns = [
         '**/[^_]*.{markdown,mdown,mkdn,mkd,mdwn,md,mdx}',
         ...getBlocklist().map(blocked => `!${toCaseInsensitiveGlob(blocked)}${blocked.endsWith('/') ? '**' : ''}`),
@@ -77,14 +98,18 @@ function portalDocsLoader(): Loader {
           return context.parseData(props)
         },
       }
-      await glob({ base: docsBasePath, pattern: patterns }).load(wrappedContext)
+      await glob({ base: docsBasePath, pattern: patterns, generateId: ({ entry }) => toCollectionId(entry, homepage) }).load(wrappedContext)
     },
   }
 }
 
 export const collections = {
   docs: defineCollection({
-    loader: portalDocsLoader(),
+        loader: portalDocsLoader(),
     schema: docsSchema({ extend: domainFieldsSchema }),
   }),
+  i18n: defineCollection({
+    loader: i18nLoader(),
+    schema: i18nSchema(),
+  }),
 }

package/src/lib/content-blocklist.ts

@@ -49,7 +49,7 @@ export function toTitleCase(filenameWithoutExt: string): string {
 // automaticamente pro português — quem conhece o vocabulário é o
 // repositório de conteúdo, via navigation.labelOverrides no .upcontent/config.json.
 // Fallback é sempre toTitleCase(name) quando não há override.
-export function resolveLabel(name: string): string {
+export function resolveLabel(name: string, fallback = toTitleCase(name)): string {
   const override = getPortalConfig().navigation?.labelOverrides?.[name.toLowerCase()]
-  return override ?? toTitleCase(name)
+  return override ?? fallback
 }

package/src/lib/doc-links.test.ts

@@ -41,7 +41,7 @@ describe('resolveRelated', () => {
     const result = resolveRelated(['domains/foo/prd'], allDocs as any)
     expect(result).toHaveLength(1)
     expect(result[0].title).toBe('Foo PRD')
-    expect(result[0].slug).toBe('domains/foo/prd')
+    expect(result[0].slug).toBe('domains/foo/prd/')
   })
 
   it('resolve entry referenciado com extensão .md', () => {
@@ -59,4 +59,24 @@ describe('resolveRelated', () => {
     const result = resolveRelated(['domains/bar/trd'], allDocs as any)
     expect(result[0].title).toBe('domains/bar/trd')
   })
+
+  it('resolve extensões alternativas e as rotas distintas de index e README', () => {
+    const docs = [
+      { id: 'index', data: { title: 'Home' } },
+      { id: 'readme', data: { title: 'README' } },
+      { id: 'guides/legacy', data: { title: 'Legacy' } },
+    ]
+
+    expect(resolveRelated(['index.md', 'README.markdown', 'guides/legacy.mdx'], docs as any)).toEqual([
+      { slug: '', title: 'Home' },
+      { slug: 'readme/', title: 'README' },
+      { slug: 'guides/legacy/', title: 'Legacy' },
+    ])
+  })
+
+  it('mantém links para README em consumers sem index dedicado', () => {
+    expect(resolveRelated(['README.markdown'], [{ id: 'index', data: { title: 'README' } }] as any)).toEqual([
+      { slug: '', title: 'README' },
+    ])
+  })
 })

package/src/lib/doc-links.ts

@@ -1,4 +1,5 @@
 import type { CollectionEntry } from 'astro:content'
+import { stripMarkdownExtension } from './markdown'
 
 export function buildGitHubUrl(
   repoUrl: string | undefined,
@@ -21,11 +22,15 @@ export function resolveRelated(
 ): RelatedDoc[] {
   if (!related || related.length === 0) return []
   return related.flatMap(ref => {
-    const normalized = ref.endsWith('.md') ? ref : `${ref}.md`
-    const entry = allDocs.find(d => d.id === normalized)
+    const normalized = stripMarkdownExtension(ref).toLowerCase()
+    const candidates = normalized === 'readme' ? ['readme', 'index'] : [normalized]
+    const entry = candidates.flatMap(candidate => allDocs.filter(d => [d.id, d.filePath]
+      .filter((path): path is string => Boolean(path))
+      .some(path => stripMarkdownExtension(path).toLowerCase() === candidate)))[0]
     if (!entry) return []
-    const slug = normalized.replace(/\.md$/, '')
-    const title = (entry.data as Record<string, unknown>).title as string | undefined ?? slug
+    const entryId = stripMarkdownExtension(entry.id).toLowerCase()
+    const slug = entryId === 'index' ? '' : entryId === 'readme' ? 'readme/' : `${entryId}/`
+    const title = (entry.data as Record<string, unknown>).title as string | undefined ?? entryId
     return [{ slug, title }]
   })
 }

package/src/lib/homepage.ts

@@ -0,0 +1,16 @@
+import { readdirSync, statSync } from 'node:fs'
+import { isBlocked } from './content-blocklist'
+import { MARKDOWN_EXTENSION, stripMarkdownExtension } from './markdown'
+
+export function hasRootIndex(docsRoot: string): boolean {
+  try {
+    return readdirSync(docsRoot).some(name =>
+      MARKDOWN_EXTENSION.test(name)
+      && statSync(`${docsRoot}/${name}`).isFile()
+      && stripMarkdownExtension(name).toLowerCase() === 'index'
+      && !isBlocked(name),
+    )
+  } catch {
+    return false
+  }
+}

package/src/lib/markdown.ts

@@ -0,0 +1,6 @@
+export const MARKDOWN_EXTENSIONS = ['.markdown', '.mdown', '.mkdn', '.mkd', '.mdwn', '.md', '.mdx'] as const
+export const MARKDOWN_EXTENSION = /\.(?:markdown|mdown|mkdn|mkd|mdwn|md|mdx)$/i
+
+export function stripMarkdownExtension(path: string): string {
+  return path.replace(MARKDOWN_EXTENSION, '')
+}

package/src/lib/portal-config.test.ts

@@ -21,6 +21,14 @@ describe('getPortalConfig', () => {
     expect(config).toEqual({})
   })
 
+  it('mantém SEO desativado quando a política não está configurada', async () => {
+    vi.mocked(fs.existsSync).mockReturnValue(true)
+    vi.mocked(fs.readFileSync).mockReturnValue(JSON.stringify({ site: { url: 'https://docs.example.com' } }))
+    const { getPortalConfig } = await import('./portal-config')
+
+    expect(getPortalConfig().seo?.enabled).toBe(false)
+  })
+
   it('retorna config parseada quando config.json existe e é válido', async () => {
     vi.mocked(fs.existsSync).mockReturnValue(true)
     vi.mocked(fs.readFileSync).mockReturnValue(
@@ -32,7 +40,8 @@ describe('getPortalConfig', () => {
           logo: { src: '/logo.svg', alt: 'Meu Portal', replacesTitle: true },
           favicon: '/favicon.svg',
         },
-         repo: { url: 'https://github.com/org/repo' },
+          seo: { enabled: true },
+          repo: { url: 'https://github.com/org/repo' },
          theme: { customCss: ['.upcontent/theme.css'] },
          starlight: {
            social: [{ icon: 'github', label: 'GitHub', href: 'https://github.com/org/repo' }],
@@ -49,6 +58,7 @@ describe('getPortalConfig', () => {
     expect(config.site?.title).toBe('Meu Portal')
     expect(config.site?.description).toBe('Documentação do time')
     expect(config.site?.url).toBe('https://docs.example.com')
+    expect(config.seo?.enabled).toBe(true)
     expect(config.site?.logo?.src).toBe('/logo.svg')
     expect(config.site?.favicon).toBe('/favicon.svg')
     expect(config.repo?.url).toBe('https://github.com/org/repo')

package/src/lib/portal-config.ts

@@ -24,10 +24,16 @@ export interface PortalConfigSite {
   title?: string
   description?: string
   url?: string
+  socialImage?: string
+  locale?: string
   logo?: PortalConfigLogo
   favicon?: string
 }
 
+export interface PortalConfigSeo {
+  enabled?: boolean
+}
+
 export interface PortalConfigTheme {
   customCss?: string[]
 }
@@ -42,6 +48,7 @@ export interface PortalConfigStarlight {
 
 export interface PortalConfig {
   site?: PortalConfigSite
+  seo?: PortalConfigSeo
   repo?: { url?: string }
   theme?: PortalConfigTheme
   starlight?: PortalConfigStarlight
@@ -108,6 +115,7 @@ function asTableOfContents(value: unknown): PortalConfigStarlight['tableOfConten
 function normalizeConfig(value: unknown): PortalConfig {
   const raw = asRecord(value)
   const rawSite = asRecord(raw.site)
+  const rawSeo = asRecord(raw.seo)
   const rawLogo = asRecord(rawSite.logo)
   const rawRepo = asRecord(raw.repo)
   const rawTheme = asRecord(raw.theme)
@@ -128,9 +136,12 @@ function normalizeConfig(value: unknown): PortalConfig {
       title: asString(rawSite.title),
       description: asString(rawSite.description),
       url: asString(rawSite.url),
+      socialImage: asString(rawSite.socialImage),
+      locale: asString(rawSite.locale),
       logo,
       favicon: asString(rawSite.favicon),
     },
+    seo: { enabled: rawSeo.enabled === true },
     repo: { url: asString(rawRepo.url) },
     theme: { customCss: asStringArray(rawTheme.customCss) },
     starlight: {

package/src/lib/portal-routes.test.ts

@@ -0,0 +1,73 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import { resolveMarkdownLink } from './portal-routes'
+
+const roots: string[] = []
+
+afterEach(() => {
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true })
+})
+
+function fixture(files: string[]) {
+  const root = mkdtempSync(join(tmpdir(), 'upcontent-routes-'))
+  roots.push(root)
+  for (const file of files) {
+    mkdirSync(dirname(join(root, file)), { recursive: true })
+    writeFileSync(join(root, file), '')
+  }
+  return root
+}
+
+describe('resolveMarkdownLink', () => {
+  it('resolves a README link relative to the content root', () => {
+    const root = fixture(['README.md', 'acervos/resource.md'])
+    expect(resolveMarkdownLink('acervos/resource.md', join(root, 'README.md'), root)).toBe('/acervos/resource/')
+  })
+
+  it('resolves nested links relative to the source document', () => {
+    const root = fixture(['guides/topic/current.md', 'guides/shared.md'])
+    expect(resolveMarkdownLink('../shared.md', join(root, 'guides/topic/current.md'), root)).toBe('/guides/shared/')
+  })
+
+  it('normalizes index documents to their directory route', () => {
+    const root = fixture(['guides/current.md', 'guides/index.md'])
+    expect(resolveMarkdownLink('index.md#Overview', join(root, 'guides/current.md'), root)).toBe('/guides/#Overview')
+  })
+
+  it('resolves trailing-slash links to sibling Markdown documents', () => {
+    const root = fixture(['README.md', 'showcase.md'])
+    expect(resolveMarkdownLink('showcase/', join(root, 'README.md'), root)).toBe('/showcase/')
+  })
+
+  it('normalizes route casing to match content collection ids', () => {
+    const root = fixture(['README.md', 'Guides/Getting-Started.md'])
+    expect(resolveMarkdownLink('Guides/Getting-Started.md', join(root, 'README.md'), root)).toBe('/guides/getting-started/')
+  })
+
+  it('maps README links to the portal root and preserves anchors', () => {
+    const root = fixture(['README.md'])
+    expect(resolveMarkdownLink('README.md#start', join(root, 'README.md'), root)).toBe('/#start')
+    expect(resolveMarkdownLink('README#start', join(root, 'README.md'), root)).toBe('/#start')
+  })
+
+  it('uses root index.md as the homepage when README.md is also present', () => {
+    const root = fixture(['README.md', 'index.markdown'])
+    expect(resolveMarkdownLink('index.markdown', join(root, 'README.md'), root)).toBe('/')
+    expect(resolveMarkdownLink('README.md', join(root, 'index.md'), root)).toBe('/readme/')
+  })
+
+  it('prefixes generated routes with the configured base path', () => {
+    const root = fixture(['README.md', 'guide.md'])
+    expect(resolveMarkdownLink('guide.md', join(root, 'README.md'), root, '/recursos/')).toBe('/recursos/guide/')
+  })
+
+  it('leaves external and non-document links unchanged', () => {
+    const root = fixture(['README.md', 'image.png'])
+    const source = join(root, 'README.md')
+    expect(resolveMarkdownLink('https://example.com/guide.md', source, root)).toBe('https://example.com/guide.md')
+    expect(resolveMarkdownLink('image.png', source, root)).toBe('image.png')
+    expect(resolveMarkdownLink('#section', source, root)).toBe('#section')
+  })
+})

package/src/lib/portal-routes.ts

@@ -0,0 +1,65 @@
+import { existsSync } from 'node:fs'
+import { dirname, relative, resolve, sep } from 'node:path'
+import { hasRootIndex } from './homepage'
+import { MARKDOWN_EXTENSION, MARKDOWN_EXTENSIONS, stripMarkdownExtension } from './markdown'
+
+function splitHref(href: string): { path: string; suffix: string } {
+  const match = href.match(/^([^?#]*)([?#].*)?$/)
+  return { path: match?.[1] ?? href, suffix: match?.[2] ?? '' }
+}
+
+function normalizeBasePath(basePath: string): string {
+  if (!basePath || basePath === '/') return ''
+  return `/${basePath.replace(/^\/+|\/+$/g, '')}`
+}
+
+function isExternalHref(href: string): boolean {
+  return /^(?:[a-z][a-z\d+.-]*:|\/\/)/i.test(href)
+}
+
+function documentPath(path: string): string | undefined {
+  if (MARKDOWN_EXTENSION.test(path)) {
+    return existsSync(path) ? path : undefined
+  }
+  const stem = path.endsWith(sep) ? path.slice(0, -sep.length) : path
+  for (const extension of MARKDOWN_EXTENSIONS) {
+    if (existsSync(`${stem}${extension}`)) return `${stem}${extension}`
+    if (path.endsWith('/') && existsSync(`${path}index${extension}`)) return `${path}index${extension}`
+  }
+  return undefined
+}
+
+export function toPortalRoute(path: string, basePath = '/', homepage: 'index' | 'readme' = 'readme'): string {
+  const withoutExtension = stripMarkdownExtension(path)
+  const normalizedPath = withoutExtension.toLowerCase()
+  const route = normalizedPath === homepage
+    ? ''
+    : normalizedPath === 'readme'
+      ? 'readme'
+    : normalizedPath.endsWith('/index')
+      ? normalizedPath.slice(0, -'/index'.length)
+      : normalizedPath
+  const prefix = normalizeBasePath(basePath)
+  return `${prefix}/${route.replace(/^\/+|\/+$/g, '')}/`.replace(/\/\/$/, '/')
+}
+
+export function resolveMarkdownLink(
+  href: string,
+  sourcePath: string,
+  contentRoot: string,
+  basePath = '/',
+): string {
+  if (!href || href.startsWith('#') || isExternalHref(href)) return href
+
+  const { path, suffix } = splitHref(href)
+  const candidate = resolve(path.startsWith('/') ? contentRoot : dirname(sourcePath), path)
+  const candidatePath = path.endsWith('/') ? `${candidate}${sep}` : candidate
+  const root = resolve(contentRoot)
+  if (candidate !== root && !candidate.startsWith(`${root}${sep}`)) return href
+
+  const markdownPath = documentPath(candidatePath)
+  if (!markdownPath) return href
+  const relativePath = relative(root, markdownPath).split(sep).join('/')
+  const homepage = hasRootIndex(contentRoot) ? 'index' : 'readme'
+  return `${toPortalRoute(relativePath, basePath, homepage)}${suffix}`
+}