upcontent 0.1.0 → 0.1.1

package/scripts/verify-golden-build.mjs

@@ -0,0 +1,9 @@
+import { existsSync, readFileSync } from 'node:fs'
+
+const html = readFileSync('dist/index.html', '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 (!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,21 @@ 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('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,7 +2,8 @@ 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'
@@ -10,12 +11,24 @@ import { getPortalConfig } from './lib/portal-config'
 
 export { getBlocklist, isBlocked, toRelativeDocPath }
 
+const MARKDOWN_EXTENSION = /\.(?:markdown|mdown|mkdn|mkd|mdwn|md|mdx)$/i
+
 // Campos de domínio específicos deste portal, além do schema padrão do
 // Starlight (title, description, sidebar, etc). Mantido isolado do
 // docsSchema() do Starlight pra ser testável sem precisar de um
 // 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,16 @@ 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): string {
+  const normalized = relativeFilePath.split(path.sep).join('/').replace(MARKDOWN_EXTENSION, '').toLowerCase()
+  if (normalized === 'readme') return 'index'
+  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()}]`)
 }
@@ -77,7 +96,7 @@ 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) }).load(wrappedContext)
     },
   }
 }
@@ -87,4 +106,8 @@ export const collections = {
     loader: portalDocsLoader(),
     schema: docsSchema({ extend: domainFieldsSchema }),
   }),
+  i18n: defineCollection({
+    loader: i18nLoader(),
+    schema: i18nSchema(),
+  }),
 }

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,62 @@
+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('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('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,59 @@
+import { existsSync } from 'node:fs'
+import { dirname, extname, relative, resolve, sep } from 'node:path'
+
+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 (extname(path).toLowerCase() === '.md' || extname(path).toLowerCase() === '.mdx') {
+    return existsSync(path) ? path : undefined
+  }
+  if (existsSync(`${path}.md`)) return `${path}.md`
+  if (existsSync(`${path}.mdx`)) return `${path}.mdx`
+  if (path.endsWith('/') && existsSync(`${path}index.md`)) return `${path}index.md`
+  if (path.endsWith('/') && existsSync(`${path}index.mdx`)) return `${path}index.mdx`
+  return undefined
+}
+
+export function toPortalRoute(path: string, basePath = '/'): string {
+  const withoutExtension = path.replace(/\.mdx?$/i, '')
+  const normalizedPath = withoutExtension.toLowerCase()
+  const route = normalizedPath === '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('/')
+  return `${toPortalRoute(relativePath, basePath)}${suffix}`
+}

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

@@ -0,0 +1,50 @@
+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 { unified } from 'unified'
+import remarkParse from 'remark-parse'
+import remarkRehype from 'remark-rehype'
+import rehypeStringify from 'rehype-stringify'
+import { remarkDocumentLinks } from './remark-doc-links'
+
+const roots: string[] = []
+
+afterEach(() => {
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true })
+})
+
+function render(markdown: string, source: string, root: string, basePath?: string): string {
+  return unified()
+    .use(remarkParse)
+    .use(remarkDocumentLinks, { contentRoot: root, basePath })
+    .use(remarkRehype)
+    .use(rehypeStringify)
+    .processSync({ value: markdown, path: source })
+    .toString()
+}
+
+function fixture(files: string[]) {
+  const root = mkdtempSync(join(tmpdir(), 'upcontent-markdown-links-'))
+  roots.push(root)
+  for (const file of files) {
+    mkdirSync(dirname(join(root, file)), { recursive: true })
+    writeFileSync(join(root, file), '')
+  }
+  return root
+}
+
+describe('remarkDocumentLinks', () => {
+  it('converts relative Markdown links using the source file path', () => {
+    const root = fixture(['README.md', 'acervos/resource.md'])
+    const html = render('[Resource](acervos/resource.md)', join(root, 'README.md'), root)
+    expect(html).toContain('href="/acervos/resource/"')
+  })
+
+  it('preserves external links and applies the base path to document routes', () => {
+    const root = fixture(['README.md', 'guide.md'])
+    const html = render('[Guide](guide.md) [External](https://example.com/guide.md)', join(root, 'README.md'), root, '/recursos/')
+    expect(html).toContain('href="/recursos/guide/"')
+    expect(html).toContain('href="https://example.com/guide.md"')
+  })
+})

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

@@ -0,0 +1,21 @@
+import { visit } from 'unist-util-visit'
+import { resolveMarkdownLink } from './portal-routes'
+
+interface LinkNode {
+  type: 'link'
+  url: string
+}
+
+export interface DocumentLinkOptions {
+  contentRoot: string
+  basePath?: string
+}
+
+export function remarkDocumentLinks(options: DocumentLinkOptions) {
+  return (tree: any, file: { path?: string }) => {
+    if (!file.path) return
+    visit(tree, 'link', (node: LinkNode) => {
+      node.url = resolveMarkdownLink(node.url, file.path!, options.contentRoot, options.basePath)
+    })
+  }
+}

package/src/lib/remark-wiki-links.test.ts

@@ -28,13 +28,13 @@ function renderStrict(markdown: string): string {
 describe('remarkWikiLinks', () => {
   it('resolve [[page]] simples pra /page', () => {
     const html = render('Veja [[backend/plan]] pra mais detalhes.')
-    expect(html).toContain('href="/backend/plan"')
+    expect(html).toContain('href="/backend/plan/"')
     expect(html).toContain('>backend/plan<')
   })
 
   it('resolve [[page#heading]] combinando path e anchor', () => {
     const html = render('Ver [[DESIGN-licencas#Impact Summary]].')
-    expect(html).toContain('href="/design-licencas#impact-summary"')
+    expect(html).toContain('href="/design-licencas/#impact-summary"')
   })
 
   it('resolve [[#heading]] como anchor local, sem path', () => {
@@ -44,13 +44,13 @@ describe('remarkWikiLinks', () => {
 
   it('resolve [[page|label]] usando o label como texto do link', () => {
     const html = render('Veja [[backend/plan|o plano]] aqui.')
-    expect(html).toContain('href="/backend/plan"')
+    expect(html).toContain('href="/backend/plan/"')
     expect(html).toContain('>o plano<')
   })
 
   it('normaliza espaços e maiúsculas no path', () => {
     const html = render('Ver [[Meu Documento]].')
-    expect(html).toContain('href="/meu-documento"')
+    expect(html).toContain('href="/meu-documento/"')
   })
 
   it('não afeta texto sem wiki links', () => {
@@ -61,8 +61,8 @@ describe('remarkWikiLinks', () => {
 
   it('resolve múltiplos wiki links na mesma linha', () => {
     const html = render('Ver [[a]] e também [[b]].')
-    expect(html).toContain('href="/a"')
-    expect(html).toContain('href="/b"')
+    expect(html).toContain('href="/a/"')
+    expect(html).toContain('href="/b/"')
   })
 
   // não corrompe rótulos de diagrama Mermaid que usam [[texto]] (sintaxe de subroutine node) —
@@ -78,12 +78,12 @@ describe('remarkWikiLinks', () => {
   })
 
   it('aceita um wiki link que aponta para um documento do consumer', () => {
-    expect(renderStrict('Veja [[README]].')).toContain('href="/readme"')
+    expect(renderStrict('Veja [[README]].')).toContain('href="/"')
   })
 
   it('mantém os formatos suportados sob validação estrita', () => {
     expect(renderStrict('[[#Product]] [[README#Product]] [[README|início]]')).toContain('href="#product"')
-    expect(renderStrict('[[#Product]] [[README#Product]] [[README|início]]')).toContain('href="/readme#product"')
+    expect(renderStrict('[[#Product]] [[README#Product]] [[README|início]]')).toContain('href="/#product"')
   })
 
   it('rejeita referências a arquivos que não são documentos', () => {

package/src/lib/remark-wiki-links.ts

@@ -2,6 +2,7 @@ import { existsSync } from 'node:fs'
 import { resolve, sep } from 'node:path'
 import { visit } from 'unist-util-visit'
 import { PRODUCT_NAME } from './product-identity'
+import { toPortalRoute } from './portal-routes'
 
 interface MdastText {
   type: 'text'
@@ -22,6 +23,7 @@ interface MdastParent {
 
 interface WikiLinkOptions {
   contentRoot?: string
+  basePath?: string
   failOnBrokenLinks?: boolean
 }
 
@@ -36,15 +38,15 @@ function slugifyHeading(heading: string): string {
 // Constrói a URL a partir da referência crua entre colchetes: [[#heading]] vira
 // anchor local; [[page]] vira path; [[page#heading]] combina os dois — path e
 // heading são fatiados (slugify) separadamente pra não perder o separador "#".
-function buildUrl(ref: string): string {
+function buildUrl(ref: string, basePath = '/'): string {
   if (ref.startsWith('#')) return '#' + slugifyHeading(ref.slice(1))
   const hashIndex = ref.indexOf('#')
   if (hashIndex >= 0) {
     const pagePart = ref.slice(0, hashIndex)
     const headingPart = ref.slice(hashIndex + 1)
-    return '/' + slugifyPath(pagePart) + '#' + slugifyHeading(headingPart)
+    return `${toPortalRoute(`${slugifyPath(pagePart)}.md`, basePath)}#${slugifyHeading(headingPart)}`
   }
-  return '/' + slugifyPath(ref)
+  return toPortalRoute(`${slugifyPath(ref)}.md`, basePath)
 }
 
 function pagePartOf(ref: string): string {
@@ -89,7 +91,7 @@ export function remarkWikiLinks(options: WikiLinkOptions = {}) {
           const source = file.path ? ` in ${file.path}` : ''
           throw new Error(`[${PRODUCT_NAME}] Broken wiki link [[${inner}]]${source}`)
         }
-        const url = buildUrl(ref)
+        const url = buildUrl(ref, options.basePath)
         parts.push({ type: 'link', url, title: null, children: [{ type: 'text', value: label }] })
         lastIndex = match.index + match[0].length
       }

package/src/lib/seo-sitemap.test.ts

@@ -0,0 +1,37 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import { getNoindexRoutes } from './seo-sitemap'
+
+const roots: string[] = []
+
+afterEach(() => {
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true })
+})
+
+describe('getNoindexRoutes', () => {
+  it('maps noindex frontmatter to portal routes', () => {
+    const root = mkdtempSync(join(tmpdir(), 'upcontent-seo-'))
+    roots.push(root)
+    mkdirSync(join(root, 'guides'), { recursive: true })
+    writeFileSync(join(root, 'README.md'), '---\nnoindex: true\n---\n')
+    writeFileSync(join(root, 'guides', 'internal.md'), '---\nnoindex: true\n---\n')
+    writeFileSync(join(root, 'guides', 'legacy.markdown'), '---\nnoindex: true\n---\n')
+    writeFileSync(join(root, 'guides', 'Release Notes.md'), '---\nnoindex: true\n---\n')
+    writeFileSync(join(root, 'guides', 'release#notes.md'), '---\nnoindex: true\n---\n')
+    writeFileSync(join(root, 'guides', 'release;notes.md'), '---\nnoindex: true\n---\n')
+    writeFileSync(join(root, 'guides', 'guide%23notes.md'), '---\nnoindex: true\n---\n')
+    writeFileSync(join(root, 'public.md'), '---\nnoindex: false\n---\n')
+
+    expect(getNoindexRoutes(root)).toEqual(new Set([
+      '/',
+      '/guides/internal',
+      '/guides/legacy',
+      '/guides/release%20notes',
+      '/guides/release%23notes',
+      '/guides/release;notes',
+      '/guides/guide%2523notes',
+    ]))
+  })
+})