upcontent 0.1.0 → 0.1.1

package/src/lib/seo-sitemap.ts

@@ -0,0 +1,54 @@
+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
+
+export function getNoindexRoutes(docsRoot: string): Set<string> {
+  const routes = new Set<string>()
+
+  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 = docPath.replace(MARKDOWN_EXTENSION, '').replace(/\/index$/i, '').toLowerCase()
+      const encodedRoute = toSitemapRoute(route)
+      routes.add(route === 'readme' ? '/' : `/${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

@@ -98,13 +98,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: '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')
   })
 

package/src/lib/sidebar.ts

@@ -35,6 +35,7 @@ function sortEntries(entries: SidebarEntry[]): SidebarEntry[] {
 
 function toSidebarSlug(relativePath: string): string {
   const slug = relativePath.replace(/\.mdx?$/i, '').toLowerCase()
+  if (slug === 'readme') return 'index'
   return slug.endsWith('/index') ? slug.slice(0, -'/index'.length) : slug
 }
 
@@ -106,8 +107,8 @@ export function buildSidebar(docsRoot: string): SidebarEntry[] {
   // 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 readmeIndex = entries.findIndex(e => !isSidebarGroup(e) && e.slug === 'index')
   const readme = readmeIndex >= 0 ? entries.splice(readmeIndex, 1)[0] : undefined
   const sorted = sortEntries(entries)
-  return readme ? [{ slug: 'readme', label: 'Home' }, ...sorted] : sorted
+  return readme ? [{ slug: 'index', label: 'Home' }, ...sorted] : sorted
 }

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

package/src/upcontent-cli.test.ts

@@ -0,0 +1,36 @@
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+import yaml from 'js-yaml'
+
+const cliPath = fileURLToPath(new URL('../scripts/upcontent-cli.mjs', import.meta.url))
+
+describe('upcontent init', () => {
+  it('generates a valid GitHub Actions workflow', () => {
+    const root = mkdtempSync(join(tmpdir(), 'upcontent-cli-'))
+
+    try {
+      const result = spawnSync(process.execPath, [cliPath, 'init'], { cwd: root, encoding: 'utf8' })
+      expect(result.status).toBe(0)
+
+      const workflow = readFileSync(join(root, '.github/workflows/deploy-docs.yml'), 'utf8')
+      expect(yaml.load(workflow)).toMatchObject({
+        jobs: {
+          publish: {
+            uses: 'lumamontes/upcontent/.github/workflows/reusable-pages.yml@main',
+            permissions: {
+              contents: 'read',
+              pages: 'write',
+              'id-token': 'write',
+            },
+          },
+        },
+      })
+    } finally {
+      rmSync(root, { recursive: true, force: true })
+    }
+  })
+})

package/test-fixtures/external-consumer/.upcontent/config.json

@@ -2,12 +2,16 @@
   "site": {
     "title": "External Consumer",
     "description": "A fixture proving consumer-owned configuration.",
+    "url": "https://docs.example.com",
     "logo": {
       "src": ".upcontent/logo.svg",
       "alt": "External Consumer"
     },
     "favicon": ".upcontent/favicon.svg"
   },
+  "seo": {
+    "enabled": true
+  },
   "repo": {
     "url": "https://github.com/example/external-consumer"
   },

package/test-fixtures/external-consumer/noindex.md

@@ -0,0 +1,7 @@
+---
+title: Internal reference
+description: This page should not appear in search results.
+noindex: true
+---
+
+This page is intentionally excluded from the sitemap.

package/test-fixtures/external-consumer/public.md

@@ -0,0 +1,6 @@
+---
+title: Public guide
+description: This page remains discoverable when SEO is enabled.
+---
+
+This page is included in the sitemap.

package/src/pages/index.astro

@@ -1,20 +0,0 @@
----
-// Redireciona pro README (raiz do conteúdo) — Starlight não tem homepage
-// própria sem um index.md na collection.
-import { getCollection } from 'astro:content'
-import { PRODUCT_NAME } from '../lib/product-identity'
-
-const all = await getCollection('docs')
-const readme = all.find(e => e.id.toLowerCase() === 'readme')
----
-
-{readme ? (
-  <meta http-equiv="refresh" content={`0;url=/${readme.id}/`} />
-) : (
-  <html lang="pt-BR">
-    <body>
-      <h1>{PRODUCT_NAME}</h1>
-      <p>Rode <code>make dev</code> para visualizar os documentos.</p>
-    </body>
-  </html>
-)}