upcontent 0.1.4 → 0.1.6

package/customization/config-json.md

@@ -68,7 +68,7 @@ The optional fields below cover navigation, Starlight presentation, and content
     }
   },
   "navigation": {
-    "roots": ["README.md", "guides"],
+    "roots": ["index.md", "guides"],
     "labelOverrides": { "api": "API reference" },
     "blocklist": {
       "exact": ["notes.md"],
@@ -88,7 +88,7 @@ The optional fields below cover navigation, Starlight presentation, and content
 | Group | Controls |
 | --- | --- |
 | `site` | Name, description, URL, social image, locale, logo, and favicon. |
-| `seo` | Explicitly enables search-engine discoverability. Defaults to disabled. |
+| `seo` | Explicitly enables search-engine discoverability. Defaults to disabled. See [Search engine visibility](seo/). |
 | `repo` | Source repository links. |
 | `theme` | Consumer-owned local CSS. |
 | `starlight` | Safe layout, social, table of contents, pagination, and code options. |

package/customization/navigation.md

@@ -7,7 +7,7 @@ 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.
+If the repository has a root `index.md`, it becomes the website homepage and the root `README.md` remains GitHub-only. Repositories without `index.md` keep the backwards-compatible behavior where `README.md` is the homepage.
 
 ## Select top-level roots
 

package/customization/seo.md

@@ -0,0 +1,106 @@
+---
+title: Search engine visibility
+description: Configure discoverability, metadata, canonical URLs, robots, and sitemaps for a portal.
+sidebar:
+  order: 3
+---
+
+Upcontent treats search-engine discoverability as an explicit site-level policy. SEO is disabled by default so a new portal is not indexed accidentally.
+
+## Enable discoverability
+
+Set `seo.enabled` to `true` and provide the canonical site URL:
+
+```json
+{
+  "site": {
+    "title": "Engineering Docs",
+    "description": "Documentation for the engineering team.",
+    "url": "https://docs.example.com"
+  },
+  "seo": {
+    "enabled": true
+  }
+}
+```
+
+The `site.url` value must be an absolute HTTP(S) URL. `SITE_URL` can provide the URL at build time and takes precedence for the Astro site configuration.
+
+When SEO is enabled, Upcontent generates indexable page metadata, canonical URLs, structured data, `robots.txt`, and a sitemap. The sitemap is published at `sitemap-index.xml`.
+
+## Keep a portal unlisted
+
+Omit `seo.enabled` or set it to `false` when the portal should be publicly accessible but not discoverable. Upcontent then emits:
+
+- `noindex, nofollow` page directives.
+- `Disallow: /` in `robots.txt`.
+- No indexable sitemap URLs.
+
+This is an unlisted portal, not a private portal. It does not prevent visitors from accessing pages. Use access-controlled hosting when the content must be private.
+
+## Exclude individual pages
+
+An enabled portal can exclude individual pages with page frontmatter:
+
+```yaml
+---
+title: Internal migration notes
+noindex: true
+---
+```
+
+The page remains available at its normal route, but it is emitted with `noindex, nofollow` and is omitted from the sitemap.
+
+## Page metadata
+
+Use these optional frontmatter fields when a page needs metadata different from the site defaults:
+
+```yaml
+---
+title: Consumer repository setup
+canonical: https://docs.example.com/getting-started/consumer-repository/
+image: https://docs.example.com/social-cards/consumer-repository.png
+---
+```
+
+- `title` controls the page title and generated heading metadata.
+- `description` supplies search and social description metadata.
+- `canonical` overrides the generated canonical URL and `og:url`. It must be an absolute HTTP(S) URL.
+- `image` overrides the site-level social image for that page.
+- `noindex` excludes the page from indexing and the sitemap.
+
+## Social previews
+
+Set a default social preview image in the site configuration:
+
+```json
+{
+  "site": {
+    "socialImage": "https://docs.example.com/social-card.png",
+    "locale": "en-US"
+  }
+}
+```
+
+Page-level `image` takes precedence over `site.socialImage`. Relative image paths resolve from the content repository and are converted to absolute URLs when a canonical site URL is available.
+
+## Deployment paths
+
+Set `BASE_PATH` when the portal is served below the domain root:
+
+```sh
+BASE_PATH=/engineering-docs SITE_URL=https://example.com pnpm exec astro build
+```
+
+Generated canonical URLs, sitemap entries, robots output, and internal links include the configured base path. Set `SITE_URL` or `site.url` when the host supports canonical URLs and sitemap generation.
+
+## Validate SEO output
+
+Before publishing, verify:
+
+```sh
+pnpm check
+make build CONTENT_PATH=/path/to/your-consumer-repo
+```
+
+Inspect `dist/robots.txt`, `dist/sitemap-index.xml`, and a representative page in `dist/` to confirm that the SEO policy matches the intended portal visibility.

package/index.md

@@ -18,6 +18,7 @@ Upcontent turns the documentation repository you already have into a fast, searc
 - [Run your first build](getting-started/first-build/)
 - [Configure content](customization/content/)
 - [Configure navigation](customization/navigation/)
+- [Configure search visibility](customization/seo/)
 - [Customize the portal](customization/)
 - [Validate before publishing](guides/validate-your-site/)
 - [Publish to GitHub Pages](deployment/github-pages/)

package/package.json

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

package/src/content.config.ts

@@ -86,6 +86,7 @@ function portalDocsLoader(): Loader {
       const homepage = hasRootIndex(docsBasePath) ? 'index' : 'readme'
       const patterns = [
         '**/[^_]*.{markdown,mdown,mkdn,mkd,mdwn,md,mdx}',
+        ...(homepage === 'index' ? ['![rR][eE][aA][dD][mM][eE].{markdown,mdown,mkdn,mkd,mdwn,md,mdx}'] : []),
         ...getBlocklist().map(blocked => `!${toCaseInsensitiveGlob(blocked)}${blocked.endsWith('/') ? '**' : ''}`),
       ]
       const wrappedContext: LoaderContext = {

package/src/lib/sidebar.test.ts

@@ -98,7 +98,7 @@ describe('buildSidebar', () => {
     mountFs(ROOT, { 'index.md': null, guides: { 'guide.md': null } })
 
     const sidebar = buildSidebar(ROOT)
-    expect(sidebar[0]).toEqual({ slug: 'index', label: 'Home' })
+    expect(sidebar[0]).toEqual({ slug: 'index', label: 'Getting Started' })
   })
 
   it('ignora dotfiles e dot-directories', () => {
@@ -110,13 +110,13 @@ describe('buildSidebar', () => {
   it('ignora arquivos bloqueados (floor hardcoded)', () => {
     mountFs(ROOT, { 'CLAUDE.md': null, 'README.md': null })
     const sidebar = buildSidebar(ROOT)
-    expect(sidebar).toEqual([{ slug: 'index', label: 'Home' }])
+    expect(sidebar).toEqual([{ slug: 'index', label: 'Getting Started' }])
   })
 
-  it('fixa o README em primeiro, relabelado como Home, na frente de tudo', () => {
+  it('fixa o README em primeiro, relabelado como Getting Started, 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: 'index', label: 'Home' })
+    expect(sidebar[0]).toEqual({ slug: 'index', label: 'Getting Started' })
     expect(sidebar[1].label).toBe('Historico')
   })
 
@@ -130,11 +130,11 @@ describe('buildSidebar', () => {
     expect(sidebar[0]).toEqual({ slug: 'index', label: 'Docs' })
   })
 
-  it('mantém README separado quando index.md é a homepage', () => {
+  it('não publica README 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' })
+    expect(sidebar[0]).toEqual({ slug: 'index', label: 'Getting Started' })
+    expect(sidebar).not.toContainEqual({ slug: 'readme', label: 'Readme' })
   })
 
   it('aplica labelOverrides do .upcontent/config.json em cima do Title Case', () => {

package/src/lib/sidebar.ts

@@ -98,8 +98,11 @@ export function buildSidebar(docsRoot: string): SidebarEntry[] {
   const homepage = hasRootIndex(docsRoot) ? 'index' : 'readme'
   const configuredRoots = getPortalConfig().navigation?.roots
   const visibleTopLevel = configuredRoots
-    ? topLevel.filter(({ name, isDir }) => configuredRoots.includes(name) || (!isDir && ['index', 'readme'].includes(toSidebarSlug(name, homepage))))
-    : topLevel
+    ? topLevel.filter(({ name, isDir }) =>
+      !(homepage === 'index' && !isDir && toSidebarSlug(name, homepage) === 'readme')
+      && (configuredRoots.includes(name) || (!isDir && ['index', 'readme'].includes(toSidebarSlug(name, homepage))))
+    )
+    : topLevel.filter(({ name, isDir }) => !(homepage === 'index' && !isDir && toSidebarSlug(name, homepage) === 'readme'))
 
   const entries: SidebarEntry[] = []
   for (const { name, isDir } of visibleTopLevel) {
@@ -118,5 +121,5 @@ export function buildSidebar(docsRoot: string): SidebarEntry[] {
   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 homepageEntry ? [{ slug: 'index', label: resolveLabel(homepage, 'Home') }, ...sorted] : sorted
+  return homepageEntry ? [{ slug: 'index', label: resolveLabel(homepage, 'Getting Started') }, ...sorted] : sorted
 }