upcontent 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,153 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+
+// Mock node:fs before importing the module under test
+vi.mock('node:fs', () => ({
+  existsSync: vi.fn(),
+  readFileSync: vi.fn(),
+}))
+
+import * as fs from 'node:fs'
+
+describe('getPortalConfig', () => {
+  beforeEach(() => {
+    vi.resetModules()
+    vi.resetAllMocks()
+  })
+
+  it('retorna config vazia quando config.json não existe', async () => {
+    vi.mocked(fs.existsSync).mockReturnValue(false)
+    const { getPortalConfig } = await import('./portal-config')
+    const config = 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(
+       JSON.stringify({
+        site: {
+          title: 'Meu Portal',
+          description: 'Documentação do time',
+          url: 'https://docs.example.com',
+          logo: { src: '/logo.svg', alt: 'Meu Portal', replacesTitle: true },
+          favicon: '/favicon.svg',
+        },
+          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' }],
+           tableOfContents: { minHeadingLevel: 2, maxHeadingLevel: 3 },
+           lastUpdated: true,
+           pagination: false,
+           expressiveCode: { styleOverrides: { borderRadius: '8px' } },
+         },
+         navigation: { roots: ['domains', 'shared'] },
+      })
+    )
+    const { getPortalConfig } = await import('./portal-config')
+    const config = 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')
+     expect(config.theme?.customCss).toEqual(['.upcontent/theme.css'])
+    expect(config.starlight?.social?.[0].icon).toBe('github')
+    expect(config.starlight?.tableOfContents).toEqual({ minHeadingLevel: 2, maxHeadingLevel: 3 })
+    expect(config.starlight?.lastUpdated).toBe(true)
+    expect(config.starlight?.pagination).toBe(false)
+    expect(config.starlight?.expressiveCode).toEqual({ styleOverrides: { borderRadius: '8px' } })
+    expect(config.navigation?.roots).toEqual(['domains', 'shared'])
+  })
+
+  it('retorna config vazia quando config.json é JSON inválido', async () => {
+    vi.mocked(fs.existsSync).mockReturnValue(true)
+    vi.mocked(fs.readFileSync).mockReturnValue('{ invalid json }')
+    const { getPortalConfig } = await import('./portal-config')
+    const config = getPortalConfig()
+    expect(config).toEqual({})
+  })
+
+  it('normaliza tipos inválidos sem quebrar a configuração do portal', async () => {
+    vi.mocked(fs.existsSync).mockReturnValue(true)
+    vi.mocked(fs.readFileSync).mockReturnValue(
+      JSON.stringify({ site: 'invalid', theme: { customCss: 'invalid' }, navigation: { roots: [1, 'docs'] } }),
+    )
+    const { getPortalConfig } = await import('./portal-config')
+
+    const config = getPortalConfig()
+
+    expect(config.site?.title).toBeUndefined()
+    expect(config.theme?.customCss).toBeUndefined()
+    expect(config.navigation?.roots).toEqual(['docs'])
+  })
+
+  it('navigation.roots com valor customizado sobrepõe default', async () => {
+    vi.mocked(fs.existsSync).mockReturnValue(true)
+    vi.mocked(fs.readFileSync).mockReturnValue(
+      JSON.stringify({ navigation: { roots: ['domains'] } })
+    )
+    const { getPortalConfig } = await import('./portal-config')
+    const config = getPortalConfig()
+    expect(config.navigation?.roots).toEqual(['domains'])
+  })
+
+  it('navigation.blocklist extra é retornado quando definido', async () => {
+    vi.mocked(fs.existsSync).mockReturnValue(true)
+    vi.mocked(fs.readFileSync).mockReturnValue(
+      JSON.stringify({
+        navigation: {
+          blocklist: { exact: ['rules.md'], prefixes: ['docs/'] },
+        },
+      })
+    )
+    const { getPortalConfig } = await import('./portal-config')
+    const config = getPortalConfig()
+    expect(config.navigation?.blocklist?.exact).toContain('rules.md')
+    expect(config.navigation?.blocklist?.prefixes).toContain('docs/')
+  })
+
+  it('descarta tipos inválidos nas opções curadas do Starlight', async () => {
+    vi.mocked(fs.existsSync).mockReturnValue(true)
+    vi.mocked(fs.readFileSync).mockReturnValue(
+      JSON.stringify({
+        starlight: {
+          social: [{ icon: 'github' }, { icon: 'github', label: 'GitHub', href: 'https://github.com' }],
+          tableOfContents: { minHeadingLevel: '2', maxHeadingLevel: 7 },
+          lastUpdated: 'yes',
+          pagination: 1,
+          expressiveCode: { styleOverrides: { borderRadius: 8, padding: '1rem' } },
+        },
+      }),
+    )
+    const { getPortalConfig } = await import('./portal-config')
+    const config = getPortalConfig()
+
+    expect(config.starlight?.social).toEqual([{ icon: 'github', label: 'GitHub', href: 'https://github.com' }])
+    expect(config.starlight?.tableOfContents).toEqual({ minHeadingLevel: undefined, maxHeadingLevel: undefined })
+    expect(config.starlight?.lastUpdated).toBeUndefined()
+    expect(config.starlight?.pagination).toBeUndefined()
+    expect(config.starlight?.expressiveCode).toEqual({ styleOverrides: { padding: '1rem' } })
+  })
+
+  it('descarta um intervalo inválido do sumário', async () => {
+    vi.mocked(fs.existsSync).mockReturnValue(true)
+    vi.mocked(fs.readFileSync).mockReturnValue(
+      JSON.stringify({ starlight: { tableOfContents: { minHeadingLevel: 4, maxHeadingLevel: 2 } } }),
+    )
+
+    const { getPortalConfig } = await import('./portal-config')
+    expect(getPortalConfig().starlight?.tableOfContents).toBeUndefined()
+  })
+})

package/src/lib/portal-config.ts

@@ -0,0 +1,187 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+export interface PortalConfigNavigation {
+  roots?: string[]
+  blocklist?: {
+    exact?: string[]
+    prefixes?: string[]
+  }
+  // Sobrescreve o label derivado automaticamente (Title Case, sem acentos)
+  // pro nome de pasta/arquivo indicado — chave em minúsculo, sem extensão
+  // (ex: "historico" -> "Histórico"). Sem isso não há como recuperar
+  // acentuação a partir de um nome de arquivo ASCII.
+  labelOverrides?: Record<string, string>
+}
+
+export interface PortalConfigLogo {
+  src: string
+  alt?: string
+  replacesTitle?: boolean
+}
+
+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[]
+}
+
+export interface PortalConfigStarlight {
+  social?: { icon: string; label: string; href: string }[]
+  tableOfContents?: false | { minHeadingLevel?: number; maxHeadingLevel?: number }
+  lastUpdated?: boolean
+  pagination?: boolean
+  expressiveCode?: false | { styleOverrides?: Record<string, string> }
+}
+
+export interface PortalConfig {
+  site?: PortalConfigSite
+  seo?: PortalConfigSeo
+  repo?: { url?: string }
+  theme?: PortalConfigTheme
+  starlight?: PortalConfigStarlight
+  navigation?: PortalConfigNavigation
+  content?: { titleField?: string }
+}
+
+const CONFIG_PATH = join(process.cwd(), 'src/content/docs/.upcontent/config.json')
+
+let _cache: PortalConfig | null = null
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : {}
+}
+
+function asString(value: unknown): string | undefined {
+  return typeof value === 'string' && value.length > 0 ? value : undefined
+}
+
+function asStringArray(value: unknown): string[] | undefined {
+  if (!Array.isArray(value)) return undefined
+  const values = value.filter((item): item is string => typeof item === 'string' && item.length > 0)
+  return values.length > 0 ? values : []
+}
+
+function asStringRecord(value: unknown): Record<string, string> | undefined {
+  const record = asRecord(value)
+  const entries: [string, string][] = []
+  for (const [key, item] of Object.entries(record)) {
+    if (typeof item === 'string') entries.push([key, item])
+  }
+  return entries.length > 0 ? Object.fromEntries(entries) : undefined
+}
+
+function asSocialLinks(value: unknown): PortalConfigStarlight['social'] {
+  if (!Array.isArray(value)) return undefined
+  const links = value.flatMap(item => {
+    const link = asRecord(item)
+    const icon = asString(link.icon)
+    const label = asString(link.label)
+    const href = asString(link.href)
+    return icon && label && href ? [{ icon, label, href }] : []
+  })
+  return links.length > 0 ? links : []
+}
+
+function asHeadingLevel(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isInteger(value) && value >= 1 && value <= 6 ? value : undefined
+}
+
+function asTableOfContents(value: unknown): PortalConfigStarlight['tableOfContents'] {
+  if (value === false) return false
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return undefined
+
+  const raw = asRecord(value)
+  const minHeadingLevel = asHeadingLevel(raw.minHeadingLevel)
+  const maxHeadingLevel = asHeadingLevel(raw.maxHeadingLevel)
+  if (minHeadingLevel !== undefined && maxHeadingLevel !== undefined && minHeadingLevel > maxHeadingLevel) {
+    return undefined
+  }
+  return { minHeadingLevel, maxHeadingLevel }
+}
+
+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)
+  const rawStarlight = asRecord(raw.starlight)
+  const rawExpressiveCode = rawStarlight.expressiveCode
+  const rawExpressive = asRecord(rawExpressiveCode)
+  const rawNavigation = asRecord(raw.navigation)
+  const rawBlocklist = asRecord(rawNavigation.blocklist)
+  const rawContent = asRecord(raw.content)
+
+  const logoSrc = asString(rawLogo.src)
+  const logo = logoSrc
+    ? { src: logoSrc, alt: asString(rawLogo.alt), replacesTitle: rawLogo.replacesTitle === true }
+    : undefined
+
+  return {
+    site: {
+      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: {
+      social: asSocialLinks(rawStarlight.social),
+      tableOfContents: asTableOfContents(rawStarlight.tableOfContents),
+      lastUpdated: typeof rawStarlight.lastUpdated === 'boolean' ? rawStarlight.lastUpdated : undefined,
+      pagination: typeof rawStarlight.pagination === 'boolean' ? rawStarlight.pagination : undefined,
+      expressiveCode: rawExpressiveCode === false
+        ? false
+        : rawExpressiveCode && typeof rawExpressiveCode === 'object'
+          ? { styleOverrides: asStringRecord(rawExpressive.styleOverrides) }
+          : undefined,
+    },
+    navigation: {
+      roots: asStringArray(rawNavigation.roots),
+      blocklist: {
+        exact: asStringArray(rawBlocklist.exact),
+        prefixes: asStringArray(rawBlocklist.prefixes),
+      },
+      labelOverrides: asStringRecord(rawNavigation.labelOverrides),
+    },
+    content: { titleField: asString(rawContent.titleField) },
+  }
+}
+
+export function getPortalConfig(): PortalConfig {
+  if (_cache !== null) return _cache
+  if (!existsSync(CONFIG_PATH)) {
+    _cache = {}
+    return _cache
+  }
+  try {
+    _cache = normalizeConfig(JSON.parse(readFileSync(CONFIG_PATH, 'utf-8')))
+  } catch {
+    _cache = {}
+  }
+  return _cache
+}
+
+// Exposed for testing — resets the singleton cache
+export function _resetPortalConfigCache(): void {
+  _cache = null
+}

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/product-identity.ts

@@ -0,0 +1,2 @@
+export const PRODUCT_NAME = 'Upcontent'
+export const PRODUCT_TAGLINE = 'Create a beautiful, customizable Starlight portal from your documentation repository.'

package/src/lib/rehype-callouts.test.ts

@@ -0,0 +1,69 @@
+import { describe, it, expect } from 'vitest'
+import { unified } from 'unified'
+import remarkParse from 'remark-parse'
+import remarkRehype from 'remark-rehype'
+import rehypeStringify from 'rehype-stringify'
+import { rehypeCallouts } from './rehype-callouts'
+
+function render(markdown: string): string {
+  return unified()
+    .use(remarkParse)
+    .use(remarkRehype)
+    .use(rehypeCallouts)
+    .use(rehypeStringify)
+    .processSync(markdown)
+    .toString()
+}
+
+describe('rehypeCallouts', () => {
+  it('converte [!info] sem texto adicional em callout com título default e ícone', () => {
+    const html = render('> [!info]')
+    expect(html).toContain('class="callout callout-info"')
+    expect(html).toContain('callout-title')
+    expect(html).toContain('ℹ️')
+    expect(html).toContain('Info')
+    expect(html).not.toContain('<blockquote>')
+  })
+
+  // formato real usado no conteúdo: marcador + texto tudo na mesma linha
+  it('converte [!info] com texto na mesma linha (formato usado no conteúdo real)', () => {
+    const html = render('> [!info] SDD — Artefato Plano técnico para a camada frontend')
+    expect(html).toContain('class="callout callout-info"')
+    expect(html).toContain('SDD — Artefato Plano técnico para a camada frontend')
+  })
+
+  it('converte [!warning] com título customizado', () => {
+    const html = render('> [!warning] Cuidado aqui\n> Detalhes do risco')
+    expect(html).toContain('class="callout callout-warning"')
+    expect(html).toContain('Cuidado aqui')
+    expect(html).toContain('⚠️')
+  })
+
+  it('cobre todos os tipos de callout usados no conteúdo', () => {
+    const types = ['info', 'note', 'warning', 'danger', 'tip', 'important', 'caution']
+    for (const type of types) {
+      const html = render(`> [!${type}] Texto`)
+      expect(html).toContain(`class="callout callout-${type}"`)
+    }
+  })
+
+  it('não quebra blockquote comum sem marcador de callout', () => {
+    const html = render('> Só uma citação normal, sem marcador')
+    expect(html).toContain('<blockquote>')
+    expect(html).not.toContain('callout')
+  })
+
+  it('callout dentro de uma lista não quebra a renderização', () => {
+    const html = render('- item 1\n  > [!tip] dica dentro da lista\n- item 2')
+    expect(html).toContain('class="callout callout-tip"')
+    expect(html).toContain('item 1')
+    expect(html).toContain('item 2')
+  })
+
+  it('tipo desconhecido sem texto usa ícone default e title case do tipo', () => {
+    const html = render('> [!custom]')
+    expect(html).toContain('class="callout callout-custom"')
+    expect(html).toContain('Custom')
+    expect(html).toContain('ℹ️')
+  })
+})

package/src/lib/rehype-callouts.ts

@@ -0,0 +1,61 @@
+import { visit } from 'unist-util-visit'
+
+interface HastText {
+  type: 'text'
+  value: string
+}
+
+interface HastElement {
+  type: 'element'
+  tagName: string
+  properties?: Record<string, unknown>
+  children: (HastElement | HastText)[]
+}
+
+const ICONS: Record<string, string> = {
+  info: 'ℹ️',
+  note: '📝',
+  warning: '⚠️',
+  danger: '🚨',
+  tip: '💡',
+  important: '❗',
+  caution: '⚠️',
+}
+
+// Rehype plugin: converts > [!type] Title callouts (formato Obsidian) AFTER remark-to-rehype
+export function rehypeCallouts() {
+  return (tree: HastElement) => {
+    visit(tree, 'element', (node: HastElement) => {
+      if (node.tagName !== 'blockquote') return
+      const firstP = node.children?.find((c): c is HastElement => c.type === 'element' && c.tagName === 'p')
+      if (!firstP) return
+      const firstText = firstP.children?.find((c): c is HastText => c.type === 'text')
+      if (!firstText) return
+      const match = firstText.value.match(/^\[!([\w]+)\](?:\s+(.+))?/)
+      if (!match) return
+
+      const type = match[1].toLowerCase()
+      const titleText = match[2]?.trim() ?? (type.charAt(0).toUpperCase() + type.slice(1))
+      const afterMarker = firstText.value.replace(/^\[![\w]+\][^\n]*\n?/, '').trimStart()
+
+      if (afterMarker) {
+        firstText.value = afterMarker
+      } else {
+        firstP.children = firstP.children.filter(c => c !== firstText)
+        if (firstP.children.length === 0) node.children = node.children.filter(c => c !== firstP)
+      }
+
+      node.tagName = 'div'
+      node.properties = { className: [`callout`, `callout-${type}`] }
+
+      node.children.unshift({
+        type: 'element', tagName: 'div',
+        properties: { className: ['callout-title'] },
+        children: [
+          { type: 'element', tagName: 'span', properties: {}, children: [{ type: 'text', value: ICONS[type] ?? 'ℹ️' }] },
+          { type: 'text', value: ' ' + titleText },
+        ],
+      })
+    })
+  }
+}

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)
+    })
+  }
+}