upcontent 0.1.1 → 0.1.3

package/.upcontent/config.json

@@ -41,7 +41,7 @@
   },
   "navigation": {
     "roots": [
-      "README.md",
+      "index.md",
       "getting-started",
       "guides",
       "customization",
@@ -72,11 +72,13 @@
         "AGENTS.md",
         "CLAUDE.md",
         "CONTEXT.md",
-        "PRODUCT.md"
+        "PRODUCT.md",
+        "README.md"
       ]
     },
     "labelOverrides": {
-      "docs": "Project Docs"
+      "docs": "Project Docs",
+      "readme": "Repository README"
     }
   },
   "content": {

package/README.md

@@ -1,8 +1,3 @@
----
-heading: Upcontent
-description: Turn a documentation repository into a fast, searchable, customizable static portal.
----
-
 <div align="center">
 
 # Upcontent

package/astro.config.mjs

@@ -14,6 +14,7 @@ import { remarkDocumentLinks } from './src/lib/remark-doc-links.ts'
 import { getPortalConfig } from './src/lib/portal-config.ts'
 import { buildSidebar } from './src/lib/sidebar.ts'
 import { getNoindexRoutes } from './src/lib/seo-sitemap.ts'
+import { hasRootIndex } from './src/lib/homepage.ts'
 import { PRODUCT_NAME, PRODUCT_TAGLINE } from './src/lib/product-identity.ts'
 
 const docsRoot = fileURLToPath(new URL('./src/content/docs', import.meta.url))
@@ -22,14 +23,20 @@ const portalConfig = getPortalConfig()
 function copyContentAssetDirectory(assetPath) {
   const source = resolve(docsRoot, assetPath)
   const target = resolve(process.cwd(), 'public', assetPath)
+  const readmeTarget = resolve(process.cwd(), 'public', 'readme', assetPath)
+  const hasHomepage = hasRootIndex(docsRoot)
+  const targets = hasHomepage ? [target, readmeTarget] : [target]
+  if (!hasHomepage) rmSync(readmeTarget, { force: true, recursive: true })
   if (!existsSync(source) || !statSync(source).isDirectory()) {
-    rmSync(target, { force: true, recursive: true })
+    for (const target of targets) rmSync(target, { force: true, recursive: true })
     return
   }
 
-  rmSync(target, { force: true, recursive: true })
-  mkdirSync(resolve(target, '..'), { recursive: true })
-  cpSync(source, target, { recursive: true })
+  for (const target of targets) {
+    rmSync(target, { force: true, recursive: true })
+    mkdirSync(resolve(target, '..'), { recursive: true })
+    cpSync(source, target, { recursive: true })
+  }
 }
 
 copyContentAssetDirectory('assets/readme')
@@ -156,8 +163,8 @@ export default defineConfig({
     processor: unified({
       remarkPlugins: [
         remarkStripDuplicateTitle,
-        [remarkWikiLinks, { contentRoot: docsRoot, basePath: import.meta.env.BASE_URL, failOnBrokenLinks: true }],
-        [remarkDocumentLinks, { contentRoot: docsRoot, basePath: import.meta.env.BASE_URL }],
+         [remarkWikiLinks, { contentRoot: docsRoot, basePath: base || '/', failOnBrokenLinks: true }],
+         [remarkDocumentLinks, { contentRoot: docsRoot, basePath: base || '/' }],
         remarkMermaid,
         remarkStructuredDataPreview,
       ],

package/customization/navigation.md

@@ -7,6 +7,8 @@ sidebar:
 
 The sidebar is generated from the consumer file structure. Use configuration when the default filesystem order is not the right experience for readers.
 
+If the repository has a root `index.md`, it becomes the website homepage and a root `README.md` remains available at `/readme/`. Repositories without `index.md` keep the backwards-compatible behavior where `README.md` is the homepage.
+
 ## Select top-level roots
 
 ```json

package/index.md

@@ -0,0 +1,19 @@
+---
+heading: Upcontent
+description: Turn a documentation repository into a fast, searchable, customizable static portal.
+sidebar:
+  order: 1
+---
+
+Upcontent turns a Markdown repository into a documentation site that is ready to share.
+
+It adds clear navigation, full-text search, technical content rendering, consumer-owned branding, and a repeatable static build while keeping the source repository as the source of truth.
+
+## Start here
+
+- [Set up a consumer repository](getting-started/consumer-repository/)
+- [Run your first build](getting-started/first-build/)
+- [Customize the portal](customization/)
+- [Validate before publishing](guides/validate-your-site/)
+
+The [repository README](readme/) contains the project and development details for Upcontent itself.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "upcontent",
   "type": "module",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "packageManager": "pnpm@10.20.0",
   "repository": {
     "type": "git",

package/scripts/verify-golden-build.mjs

@@ -1,9 +1,12 @@
-import { existsSync, readFileSync } from 'node:fs'
+import { existsSync } from 'node:fs'
 
-const html = readFileSync('dist/index.html', 'utf8')
+const htmlPath = 'dist/index.html'
 const requiredAssets = ['assets/readme/portal-home.png', 'assets/readme/portal-showcase.png']
 
+if (!existsSync(htmlPath)) throw new Error(`Golden build is missing: ${htmlPath}`)
+
 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}`)
 }
+
+if (existsSync('dist/readme/index.html')) throw new Error('Golden build unexpectedly published README as a portal route')

package/src/content.config.test.ts

@@ -195,6 +195,11 @@ describe('toCollectionId', () => {
     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')
   })

package/src/content.config.ts

@@ -7,12 +7,12 @@ 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 }
 
-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
@@ -65,9 +65,10 @@ export function resolveTitle(relativeFilePath: string, data: Record<string, unkn
   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'
+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
 }
 
@@ -82,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('/') ? '**' : ''}`),
@@ -96,14 +98,14 @@ function portalDocsLoader(): Loader {
           return context.parseData(props)
         },
       }
-      await glob({ base: docsBasePath, pattern: patterns, generateId: ({ entry }) => toCollectionId(entry) }).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({

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-routes.test.ts

@@ -36,6 +36,11 @@ describe('resolveMarkdownLink', () => {
     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/')
@@ -47,6 +52,12 @@ describe('resolveMarkdownLink', () => {
     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/')

package/src/lib/portal-routes.ts

@@ -1,5 +1,7 @@
 import { existsSync } from 'node:fs'
-import { dirname, extname, relative, resolve, sep } from 'node:path'
+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(/^([^?#]*)([?#].*)?$/)
@@ -16,21 +18,24 @@ function isExternalHref(href: string): boolean {
 }
 
 function documentPath(path: string): string | undefined {
-  if (extname(path).toLowerCase() === '.md' || extname(path).toLowerCase() === '.mdx') {
+  if (MARKDOWN_EXTENSION.test(path)) {
     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`
+  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 = '/'): string {
-  const withoutExtension = path.replace(/\.mdx?$/i, '')
+export function toPortalRoute(path: string, basePath = '/', homepage: 'index' | 'readme' = 'readme'): string {
+  const withoutExtension = stripMarkdownExtension(path)
   const normalizedPath = withoutExtension.toLowerCase()
-  const route = normalizedPath === 'readme'
+  const route = normalizedPath === homepage
     ? ''
+    : normalizedPath === 'readme'
+      ? 'readme'
     : normalizedPath.endsWith('/index')
       ? normalizedPath.slice(0, -'/index'.length)
       : normalizedPath
@@ -55,5 +60,6 @@ export function resolveMarkdownLink(
   const markdownPath = documentPath(candidatePath)
   if (!markdownPath) return href
   const relativePath = relative(root, markdownPath).split(sep).join('/')
-  return `${toPortalRoute(relativePath, basePath)}${suffix}`
+  const homepage = hasRootIndex(contentRoot) ? 'index' : 'readme'
+  return `${toPortalRoute(relativePath, basePath, homepage)}${suffix}`
 }

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

@@ -78,12 +78,14 @@ describe('remarkWikiLinks', () => {
   })
 
   it('aceita um wiki link que aponta para um documento do consumer', () => {
-    expect(renderStrict('Veja [[README]].')).toContain('href="/"')
+    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="/#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,8 @@ 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 {
@@ -35,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, basePath = '/'): 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 `${toPortalRoute(`${slugifyPath(pagePart)}.md`, basePath)}#${slugifyHeading(headingPart)}`
+    return `${pageRoute(pagePart, basePath, homepage)}#${slugifyHeading(headingPart)}`
   }
-  return toPortalRoute(`${slugifyPath(ref)}.md`, basePath)
+  return pageRoute(ref, basePath, homepage)
 }
 
 function pagePartOf(ref: string): string {
@@ -59,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)[] = []
@@ -91,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, options.basePath)
+        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

@@ -34,4 +34,13 @@ describe('getNoindexRoutes', () => {
       '/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

@@ -1,11 +1,12 @@
 import { readdirSync, readFileSync, statSync } from 'node:fs'
 import { join, relative } from 'node:path'
 import { load as parseYaml } from 'js-yaml'
-
-const MARKDOWN_EXTENSION = /\.(?:markdown|mdown|mkdn|mkd|mdwn|md|mdx)$/i
+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)) {
@@ -32,9 +33,9 @@ export function getNoindexRoutes(docsRoot: string): Set<string> {
       }
 
       const docPath = relative(docsRoot, filePath).replace(/\\/g, '/')
-      const route = docPath.replace(MARKDOWN_EXTENSION, '').replace(/\/index$/i, '').toLowerCase()
+       const route = stripMarkdownExtension(docPath).replace(/\/index$/i, '').toLowerCase()
       const encodedRoute = toSitemapRoute(route)
-      routes.add(route === 'readme' ? '/' : `/${encodedRoute}`)
+       routes.add(route === homepage ? '/' : `/${encodedRoute}`)
     }
   }
 

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 }[]
@@ -108,6 +120,23 @@ describe('buildSidebar', () => {
     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,12 +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()
-  if (slug === 'readme') return 'index'
+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").
@@ -59,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)
@@ -87,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 === 'index')
-  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: 'index', 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>