upcontent 0.1.0 → 0.1.2

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,14 @@ 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="/readme/"')
+    expect(renderStrict('Veja [[README.md]].')).toContain('href="/readme/"')
+    expect(renderStrict('Veja [[index]].')).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="/readme/#product"')
   })
 
   it('rejeita referências a arquivos que não são documentos', () => {

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

@@ -2,6 +2,9 @@ import { existsSync } from 'node:fs'
 import { resolve, sep } from 'node:path'
 import { visit } from 'unist-util-visit'
 import { PRODUCT_NAME } from './product-identity'
+import { hasRootIndex } from './homepage'
+import { MARKDOWN_EXTENSION, MARKDOWN_EXTENSIONS, stripMarkdownExtension } from './markdown'
+import { toPortalRoute } from './portal-routes'
 
 interface MdastText {
   type: 'text'
@@ -22,6 +25,7 @@ interface MdastParent {
 
 interface WikiLinkOptions {
   contentRoot?: string
+  basePath?: string
   failOnBrokenLinks?: boolean
 }
 
@@ -33,18 +37,23 @@ function slugifyHeading(heading: string): string {
   return heading.toLowerCase().replace(/\s+/g, '-').replace(/[^\w-]/g, '')
 }
 
+function pageRoute(pagePart: string, basePath: string, homepage: 'index' | 'readme'): string {
+  const withoutExtension = stripMarkdownExtension(pagePart)
+  return toPortalRoute(`${slugifyPath(withoutExtension)}.md`, basePath, homepage)
+}
+
 // 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 = '/', homepage: 'index' | 'readme' = 'readme'): 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 `${pageRoute(pagePart, basePath, homepage)}#${slugifyHeading(headingPart)}`
   }
-  return '/' + slugifyPath(ref)
+  return pageRoute(ref, basePath, homepage)
 }
 
 function pagePartOf(ref: string): string {
@@ -57,16 +66,16 @@ function wikiLinkResolves(ref: string, contentRoot: string): boolean {
   if (!pagePart) return true
   const target = resolve(contentRoot, pagePart)
   if (!target.startsWith(`${resolve(contentRoot)}${sep}`)) return false
-  if (/\.(?!mdx?$)[^/]+$/i.test(pagePart)) return false
-  const withoutExtension = target.replace(/\.mdx?$/i, '')
-  return [`${withoutExtension}.md`, `${withoutExtension}.mdx`, resolve(target, 'index.md'), resolve(target, 'index.mdx')]
-    .some(candidate => existsSync(candidate))
+  if (/\.[^/]+$/i.test(pagePart) && !MARKDOWN_EXTENSION.test(pagePart)) return false
+  const withoutExtension = stripMarkdownExtension(target)
+  return MARKDOWN_EXTENSIONS.some(extension => existsSync(`${withoutExtension}${extension}`) || existsSync(resolve(target, `index${extension}`)))
 }
 
 // Remark plugin: converts [[page]] / [[#heading]] / [[page#heading]] / [[page|label]]
 // Obsidian wiki links pra links markdown normais.
 export function remarkWikiLinks(options: WikiLinkOptions = {}) {
   return (tree: MdastParent, file: { path?: string }) => {
+    const homepage = options.contentRoot && hasRootIndex(options.contentRoot) ? 'index' : 'readme'
     visit(tree, 'text', (node: MdastText, index: number | undefined, parent: MdastParent | undefined) => {
       if (!node.value.includes('[[')) return
       const parts: (MdastText | MdastLink)[] = []
@@ -89,7 +98,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, homepage)
         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,46 @@
+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',
+    ]))
+  })
+
+  it('keeps a noindex README separate when index.md is the homepage', () => {
+    const root = mkdtempSync(join(tmpdir(), 'upcontent-seo-'))
+    roots.push(root)
+    writeFileSync(join(root, 'index.md'), '# Home\n')
+    writeFileSync(join(root, 'README.md'), '---\nnoindex: true\n---\n')
+
+    expect(getNoindexRoutes(root)).toEqual(new Set(['/readme']))
+  })
+})

package/src/lib/seo-sitemap.ts

@@ -0,0 +1,55 @@
+import { readdirSync, readFileSync, statSync } from 'node:fs'
+import { join, relative } from 'node:path'
+import { load as parseYaml } from 'js-yaml'
+import { hasRootIndex } from './homepage'
+import { MARKDOWN_EXTENSION, stripMarkdownExtension } from './markdown'
+
+export function getNoindexRoutes(docsRoot: string): Set<string> {
+  const routes = new Set<string>()
+  const homepage = hasRootIndex(docsRoot) ? 'index' : 'readme'
+
+  function visitDirectory(directory: string): void {
+    for (const name of readdirSync(directory)) {
+      if (name.startsWith('.')) continue
+      const filePath = join(directory, name)
+      if (statSync(filePath).isDirectory()) {
+        visitDirectory(filePath)
+        continue
+      }
+      if (!MARKDOWN_EXTENSION.test(name)) continue
+
+      const source = readFileSync(filePath, 'utf8')
+      const frontmatter = source.match(/^---\s*\n([\s\S]*?)\n---(?:\s|$)/)?.[1]
+      if (!frontmatter) continue
+
+      let data: unknown
+      try {
+        data = parseYaml(frontmatter)
+      } catch {
+        continue
+      }
+      if (!data || typeof data !== 'object' || Array.isArray(data) || (data as Record<string, unknown>).noindex !== true) {
+        continue
+      }
+
+      const docPath = relative(docsRoot, filePath).replace(/\\/g, '/')
+       const route = stripMarkdownExtension(docPath).replace(/\/index$/i, '').toLowerCase()
+      const encodedRoute = toSitemapRoute(route)
+       routes.add(route === homepage ? '/' : `/${encodedRoute}`)
+    }
+  }
+
+  try {
+    visitDirectory(docsRoot)
+  } catch {
+    return routes
+  }
+  return routes
+}
+
+function toSitemapRoute(route: string): string {
+  const path = route
+    .replace(/%/g, '%25')
+    .replace(/[?#]/g, character => character === '?' ? '%3F' : '%23')
+  return new URL(`https://upcontent.invalid/${path}`).pathname.replace(/^\//, '')
+}

package/src/lib/sidebar.test.ts

@@ -38,7 +38,10 @@ function mountFs(root: string, tree: Tree) {
 
   vi.mocked(fs.statSync).mockImplementation((path: unknown) => {
     const node = lookup(String(path))
-    return { isDirectory: () => node !== null && typeof node === 'object' } as never
+    return {
+      isDirectory: () => node !== null && typeof node === 'object',
+      isFile: () => node === null,
+    } as never
   })
 }
 
@@ -89,6 +92,15 @@ describe('buildSidebar', () => {
     expect(sidebar.map(entry => entry.label)).toEqual(['Docs'])
   })
 
+  it('mantém a homepage mesmo quando roots não a lista', () => {
+    vi.mocked(fs.existsSync).mockReturnValue(true)
+    vi.mocked(fs.readFileSync).mockReturnValue(JSON.stringify({ navigation: { roots: ['guides'] } }))
+    mountFs(ROOT, { 'index.md': null, guides: { 'guide.md': null } })
+
+    const sidebar = buildSidebar(ROOT)
+    expect(sidebar[0]).toEqual({ slug: 'index', label: 'Home' })
+  })
+
   it('ignora dotfiles e dot-directories', () => {
     mountFs(ROOT, { '.claude': { 'x.md': null }, domains: { historico: { 'a.md': null } } })
     const sidebar = buildSidebar(ROOT) as { label: string }[]
@@ -98,16 +110,33 @@ describe('buildSidebar', () => {
   it('ignora arquivos bloqueados (floor hardcoded)', () => {
     mountFs(ROOT, { 'CLAUDE.md': null, 'README.md': null })
     const sidebar = buildSidebar(ROOT)
-    expect(sidebar).toEqual([{ slug: 'readme', label: 'Home' }])
+    expect(sidebar).toEqual([{ slug: 'index', label: 'Home' }])
   })
 
   it('fixa o README em primeiro, relabelado como Home, na frente de tudo', () => {
     mountFs(ROOT, { 'README.md': null, domains: { historico: { 'a.md': null } } })
     const sidebar = buildSidebar(ROOT) as { label: string }[]
-    expect(sidebar[0]).toEqual({ slug: 'readme', label: 'Home' })
+    expect(sidebar[0]).toEqual({ slug: 'index', label: 'Home' })
     expect(sidebar[1].label).toBe('Historico')
   })
 
+  it('permite sobrescrever o label do README', () => {
+    vi.mocked(fs.existsSync).mockReturnValue(true)
+    vi.mocked(fs.readFileSync).mockReturnValue(
+      JSON.stringify({ navigation: { labelOverrides: { readme: 'Docs' } } }),
+    )
+    mountFs(ROOT, { 'README.md': null, domains: { historico: { 'a.md': null } } })
+    const sidebar = buildSidebar(ROOT) as { label: string }[]
+    expect(sidebar[0]).toEqual({ slug: 'index', label: 'Docs' })
+  })
+
+  it('mantém README separado quando index.md é a homepage', () => {
+    mountFs(ROOT, { 'README.md': null, 'index.markdown': null, domains: { historico: { 'a.md': null } } })
+    const sidebar = buildSidebar(ROOT) as { slug?: string; label?: string }[]
+    expect(sidebar[0]).toEqual({ slug: 'index', label: 'Home' })
+    expect(sidebar).toContainEqual({ slug: 'readme', label: 'Readme' })
+  })
+
   it('aplica labelOverrides do .upcontent/config.json em cima do Title Case', () => {
     vi.mocked(fs.existsSync).mockReturnValue(true)
     vi.mocked(fs.readFileSync).mockReturnValue(

package/src/lib/sidebar.ts

@@ -1,5 +1,7 @@
 import { readdirSync, statSync } from 'node:fs'
 import { isBlocked, resolveLabel } from './content-blocklist'
+import { hasRootIndex } from './homepage'
+import { MARKDOWN_EXTENSION, stripMarkdownExtension } from './markdown'
 import { getPortalConfig } from './portal-config'
 
 // Diretórios de topo que existem só como agrupamento estrutural do
@@ -33,11 +35,18 @@ function sortEntries(entries: SidebarEntry[]): SidebarEntry[] {
   return [...entries].sort((a, b) => labelOf(a).localeCompare(labelOf(b), 'pt-BR'))
 }
 
-function toSidebarSlug(relativePath: string): string {
-  const slug = relativePath.replace(/\.mdx?$/i, '').toLowerCase()
+function toSidebarSlug(relativePath: string, homepage: 'index' | 'readme'): string {
+  const slug = stripMarkdownExtension(relativePath).toLowerCase()
+  if (slug === homepage) return 'index'
+  if (slug === 'readme') return 'readme'
   return slug.endsWith('/index') ? slug.slice(0, -'/index'.length) : slug
 }
 
+function sidebarFileEntry(relativePath: string, homepage: 'index' | 'readme'): SidebarLink {
+  const slug = toSidebarSlug(relativePath, homepage)
+  return slug === 'readme' ? { slug, label: resolveLabel('readme') } : { slug }
+}
+
 // Lista uma pasta ignorando dotfiles/dot-dirs e caminhos bloqueados
 // (ver content-blocklist.ts) — relPath é relativo à raiz do content, sem
 // barra inicial (ex: "domains/historico").
@@ -58,17 +67,17 @@ function listVisible(absDir: string, relPath: string): { name: string; isDir: bo
 // (não só o de topo) recebe label em Title Case, porque o autogenerate
 // nativo do Starlight usa o nome literal da pasta em todo nível abaixo do
 // primeiro e não expõe nenhum jeito de sobrescrever isso via config.
-function buildDir(absDir: string, relPath: string): SidebarEntry[] {
+function buildDir(absDir: string, relPath: string, homepage: 'index' | 'readme'): SidebarEntry[] {
   const entries: SidebarEntry[] = []
   for (const { name, isDir } of listVisible(absDir, relPath)) {
     const rel = relPath ? `${relPath}/${name}` : name
     if (isDir) {
-      const items = buildDir(`${absDir}/${name}`, rel)
+      const items = buildDir(`${absDir}/${name}`, rel, homepage)
       if (items.length > 0) entries.push({ label: resolveLabel(name), items })
-    } else if (/\.mdx?$/i.test(name)) {
+    } else if (MARKDOWN_EXTENSION.test(name)) {
       // Slug do Starlight = path relativo ao content root, sem extensão,
       // minúsculo (ver ADR/nota em Footer.astro — mesmo mecanismo).
-      entries.push({ slug: toSidebarSlug(rel) })
+      entries.push(sidebarFileEntry(rel, homepage))
     }
   }
   return sortEntries(entries)
@@ -86,28 +95,28 @@ export function buildSidebar(docsRoot: string): SidebarEntry[] {
     return []
   }
 
+  const homepage = hasRootIndex(docsRoot) ? 'index' : 'readme'
   const configuredRoots = getPortalConfig().navigation?.roots
   const visibleTopLevel = configuredRoots
-    ? topLevel.filter(({ name }) => configuredRoots.includes(name))
+    ? topLevel.filter(({ name, isDir }) => configuredRoots.includes(name) || (!isDir && ['index', 'readme'].includes(toSidebarSlug(name, homepage))))
     : topLevel
 
   const entries: SidebarEntry[] = []
   for (const { name, isDir } of visibleTopLevel) {
     if (isDir && FLATTEN_TOP_LEVEL_DIRS.has(name)) {
-      entries.push(...buildDir(`${docsRoot}/${name}`, name))
+      entries.push(...buildDir(`${docsRoot}/${name}`, name, homepage))
     } else if (isDir) {
-      const items = buildDir(`${docsRoot}/${name}`, name)
+      const items = buildDir(`${docsRoot}/${name}`, name, homepage)
       if (items.length > 0) entries.push({ label: resolveLabel(name), items })
-    } else if (/\.mdx?$/i.test(name)) {
-      entries.push({ slug: toSidebarSlug(name) })
+    } else if (MARKDOWN_EXTENSION.test(name)) {
+      entries.push(sidebarFileEntry(name, homepage))
     }
   }
 
-  // README fica fixo em primeiro, relabelado como "Home" — é a landing
-  // page do portal, não deveria competir alfabeticamente nem aparecer com
-  // o nome literal do arquivo.
-  const readmeIndex = entries.findIndex(e => !isSidebarGroup(e) && e.slug === 'readme')
-  const readme = readmeIndex >= 0 ? entries.splice(readmeIndex, 1)[0] : undefined
+  // A homepage fica fixa em primeiro, com o label configurável "Home" por
+  // padrão, sem competir alfabeticamente com as outras páginas.
+  const homepageIndex = entries.findIndex(e => !isSidebarGroup(e) && e.slug === 'index')
+  const homepageEntry = homepageIndex >= 0 ? entries.splice(homepageIndex, 1)[0] : undefined
   const sorted = sortEntries(entries)
-  return readme ? [{ slug: 'readme', label: 'Home' }, ...sorted] : sorted
+  return homepageEntry ? [{ slug: 'index', label: resolveLabel(homepage, 'Home') }, ...sorted] : sorted
 }

package/src/overrides/Footer.astro

@@ -23,12 +23,10 @@ const editUrl = buildGitHubUrl(repoUrl, filePath, 'edit')
 const related = entry.data.related?.length
   ? resolveRelated(
       entry.data.related,
-      (await getCollection('docs')).map(doc => ({
-        ...doc,
-        id: doc.filePath ? toRelativeDocPath(doc.filePath) : doc.id,
-      })),
+      await getCollection('docs'),
     )
   : []
+const baseUrl = import.meta.env.BASE_URL
 ---
 
 <Default><slot /></Default>
@@ -56,7 +54,7 @@ const related = entry.data.related?.length
        <h2>Related documents</h2>
       <ul>
         {related.map(doc => (
-          <li><a href={`/${doc.slug}`}>{doc.title}</a></li>
+          <li><a href={`${baseUrl}${doc.slug}`}>{doc.title}</a></li>
         ))}
       </ul>
     </section>

package/src/overrides/Head.astro

@@ -8,13 +8,96 @@ import { getPortalConfig } from '../lib/portal-config'
 import { PRODUCT_NAME } from '../lib/product-identity'
 
 const { head } = Astro.locals.starlightRoute
-const isHome = Astro.locals.starlightRoute.id === 'readme'
-const pageHead = isHome ? head.filter(({ tag }) => tag !== 'title') : head
-const siteTitle = getPortalConfig().site?.title ?? PRODUCT_NAME
+const { entry } = Astro.locals.starlightRoute
+const normalizedBasePath = import.meta.env.BASE_URL.replace(/\/+$/, '')
+const isHome = Astro.url.pathname.replace(/\/+$/, '') === normalizedBasePath
+const baseHead = isHome ? head.filter(({ tag }) => tag !== 'title') : head
+const config = getPortalConfig()
+const seoEnabled = config.seo?.enabled === true && Boolean(Astro.site)
+const siteTitle = config.site?.title ?? PRODUCT_NAME
+const pageData = entry?.data ?? {}
+const seoHead = seoEnabled
+  ? baseHead
+  : baseHead.filter(({ tag, attrs }) => {
+      const property = typeof attrs?.property === 'string' ? attrs.property : undefined
+      const name = typeof attrs?.name === 'string' ? attrs.name : undefined
+      return !(tag === 'meta' && (property?.startsWith('og:') || name?.startsWith('twitter:')))
+    })
+const canonicalTag = seoHead.find(({ tag, attrs }) => tag === 'link' && attrs?.rel === 'canonical')
+const canonicalUrl = seoEnabled
+  ? typeof pageData.canonical === 'string'
+    ? pageData.canonical
+    : typeof canonicalTag?.attrs?.href === 'string'
+      ? canonicalTag.attrs.href
+      : undefined
+  : undefined
+const pageHead = pageData.canonical || config.site?.locale
+  ? seoHead.filter(({ tag, attrs }) =>
+      !(pageData.canonical && tag === 'link' && attrs?.rel === 'canonical')
+      && !(pageData.canonical && tag === 'meta' && attrs?.property === 'og:url')
+      && !(config.site?.locale && tag === 'meta' && attrs?.property === 'og:locale'),
+    )
+  : seoHead
+const socialImage = seoEnabled && (typeof pageData.image === 'string' ? pageData.image : config.site?.socialImage)
+const robots = !seoEnabled || pageData.noindex === true ? 'noindex, nofollow' : undefined
+const pageTitle = typeof pageData.title === 'string' ? pageData.title : siteTitle
+const pageDescription = typeof pageData.description === 'string' ? pageData.description : config.site?.description
+const absoluteImage = resolveOptionalUrl(socialImage, canonicalUrl)
+const siteRoot = canonicalUrl && Astro.site ? new URL(import.meta.env.BASE_URL, Astro.site).href : undefined
+const breadcrumbItems = canonicalUrl
+  ? [{ '@type': 'ListItem', position: 1, name: siteTitle, item: siteRoot },
+     ...(isHome ? [] : [{ '@type': 'ListItem', position: 2, name: pageTitle, item: canonicalUrl }])]
+  : []
+const structuredData = canonicalUrl
+  ? {
+      '@context': 'https://schema.org',
+      '@graph': [
+        {
+          '@type': 'WebSite',
+          '@id': `${siteRoot}#website`,
+          url: siteRoot,
+          name: siteTitle,
+          description: config.site?.description,
+          inLanguage: config.site?.locale,
+        },
+        {
+          '@type': 'TechArticle',
+          '@id': `${canonicalUrl}#article`,
+          url: canonicalUrl,
+          headline: pageTitle,
+          description: pageDescription,
+          isPartOf: { '@id': `${siteRoot}#website` },
+          image: absoluteImage,
+          dateModified: pageData.updated,
+          breadcrumb: { '@type': 'BreadcrumbList', itemListElement: breadcrumbItems },
+        },
+      ],
+    }
+  : undefined;
+const structuredDataJson = structuredData
+  ? JSON.stringify(structuredData).replace(/[<>&]/g, character => ({ '<': '\\u003c', '>': '\\u003e', '&': '\\u0026' })[character]!)
+  : undefined
+
+function resolveOptionalUrl(value: unknown, baseUrl: string | undefined): string | undefined {
+  if (typeof value !== 'string' || value.length === 0) return undefined
+  try {
+    const url = new URL(value, baseUrl)
+    return url.protocol === 'http:' || url.protocol === 'https:' ? url.href : undefined
+  } catch {
+    return undefined
+  }
+}
 ---
 
 {pageHead.map(({ tag: Tag, attrs, content }) => <Tag {...attrs} set:html={content} />)}
 <slot />
 {isHome && <title>{siteTitle}</title>}
+{seoEnabled && pageData.canonical && <link rel="canonical" href={canonicalUrl} />}
+{seoEnabled && pageData.canonical && <meta property="og:url" content={canonicalUrl} />}
+{seoEnabled && config.site?.locale && <meta property="og:locale" content={config.site.locale} />}
+{absoluteImage && <meta property="og:image" content={absoluteImage} />}
+{absoluteImage && <meta name="twitter:image" content={absoluteImage} />}
+{robots && <meta name="robots" content={robots} />}
+{structuredDataJson && <script type="application/ld+json" set:html={structuredDataJson} />}
 <MermaidLoader />
 <StructuredDataCopy />

package/src/pages/robots.txt.ts

@@ -0,0 +1,46 @@
+import { getPortalConfig } from '../lib/portal-config'
+
+export const prerender = true
+
+export function GET() {
+  const config = getPortalConfig()
+  const configuredUrl = process.env.SITE_URL || config.site?.url
+  const seoEnabled = config.seo?.enabled === true && Boolean(configuredUrl)
+  if (!seoEnabled) {
+    return disallowRobots()
+  }
+
+  const basePath = process.env.BASE_PATH || ''
+  let siteUrl
+  try {
+    siteUrl = configuredUrl ? addBasePath(configuredUrl, basePath) : undefined
+  } catch {
+    return disallowRobots()
+  }
+  const sitemap = siteUrl ? `${siteUrl}/sitemap-index.xml` : undefined
+  const body = ['User-agent: *', 'Allow: /', sitemap && `Sitemap: ${sitemap}`].filter(Boolean).join('\n') + '\n'
+
+  return new Response(body, { headers: { 'Content-Type': 'text/plain; charset=utf-8' } })
+}
+
+function addBasePath(siteUrl: string, basePath: string): string {
+  const url = new URL(siteUrl)
+  if (url.protocol !== 'http:' && url.protocol !== 'https:') throw new Error('unsupported protocol')
+  if (url.username || url.password) throw new Error('userinfo is not allowed')
+  url.search = ''
+  url.hash = ''
+  const normalizedBasePath = basePath.replace(/^\/+|\/+$/g, '')
+
+  if (normalizedBasePath) {
+    url.pathname = `/${normalizedBasePath}`
+    return url.toString().replace(/\/+$/, '')
+  }
+
+  return url.toString().replace(/\/+$/, '')
+}
+
+function disallowRobots(): Response {
+  return new Response('User-agent: *\nDisallow: /\n', {
+    headers: { 'Content-Type': 'text/plain; charset=utf-8' },
+  })
+}