upcontent 0.1.0 → 0.1.2

package/.github/workflows/ci.yml

@@ -40,10 +40,10 @@ jobs:
       - name: Run Astro diagnostics
         run: pnpm check
 
-      - name: Build golden consumer
-        run: make build CONTENT_PATH=.
-
       - name: Check golden artifact
+        run: make check-golden
+
+      - name: Check golden runtime assets
         run: |
           test -f dist/index.html
           test -f dist/pagefind/pagefind.js

package/.github/workflows/publish.yml

@@ -0,0 +1,75 @@
+name: Publish npm package
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v5
+
+      - name: Set up pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10.20.0
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v5
+        with:
+          node-version: 24
+          registry-url: https://registry.npmjs.org
+          package-manager-cache: false
+
+      - name: Verify npm version
+        run: npm --version
+
+      - name: Require npm Trusted Publishing support
+        run: |
+          node -e "const [major, minor, patch] = process.argv[1].split('.').map(Number); if (major < 11 || (major === 11 && (minor < 5 || (minor === 5 && patch < 1)))) process.exit(1)" "$(npm --version)"
+
+      - name: Verify tag matches package version
+        env:
+          TAG_VERSION: ${{ github.ref_name }}
+        run: |
+          test "${TAG_VERSION#v}" = "$(node -p "require('./package.json').version")"
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Run tests
+        run: pnpm test
+
+      - name: Run Astro diagnostics
+        run: pnpm check
+
+      - name: Validate golden consumer
+        run: make check-golden
+
+      - name: Validate external consumer
+        run: make check-external
+
+      - name: Inspect package contents
+        run: npm pack --dry-run
+
+      - name: Check diff hygiene
+        run: |
+          git diff --check
+          git diff --exit-code
+          test -z "$(git status --porcelain --untracked-files=all)"
+
+      - name: Check release artifacts
+        run: |
+          test -f dist/index.html
+          test -f dist/pagefind/pagefind.js
+          test -f dist/upcontent-assets/favicon.svg
+
+      - name: Publish package
+        run: npm publish --access public

package/.upcontent/config.json

@@ -10,6 +10,9 @@
     },
     "favicon": ".upcontent/favicon.svg"
   },
+  "seo": {
+    "enabled": true
+  },
   "repo": {
     "url": "https://github.com/lumamontes/upcontent"
   },
@@ -38,6 +41,7 @@
   },
   "navigation": {
     "roots": [
+      "index.md",
       "README.md",
       "getting-started",
       "guides",
@@ -73,7 +77,8 @@
       ]
     },
     "labelOverrides": {
-      "docs": "Project Docs"
+      "docs": "Project Docs",
+      "readme": "Repository README"
     }
   },
   "content": {

package/CONTEXT.md

@@ -0,0 +1,25 @@
+# Upcontent Context
+
+Upcontent renders documentation repositories into static portals. This context defines the publication and discoverability terms used by the renderer and its consumer repositories.
+
+## Publication And Discoverability
+
+**Private source**:
+The Git repository containing the documentation is access-controlled. This says nothing about the visibility of the generated portal.
+_Avoid_: private portal
+
+**Public portal**:
+A generated portal that is publicly accessible and has explicitly enabled SEO discoverability.
+_Avoid_: public repository
+
+**Unlisted portal**:
+A publicly accessible portal that asks crawlers not to index its pages. It is not access control and must not be described as private.
+_Avoid_: private portal
+
+**Private portal**:
+A generated portal protected by the hosting layer so unauthenticated visitors and crawlers cannot access its content.
+_Avoid_: hidden portal, noindex portal
+
+**SEO policy**:
+The explicit site-level choice to enable or disable search-engine discoverability for a portal. SEO is opt-in; page-level `noindex` can narrow an enabled policy to individual pages.
+_Avoid_: SEO config, SEO mode

package/Makefile

@@ -3,7 +3,7 @@ REPO_URL ?=
 BASE_PATH ?=
 SITE_URL ?=
 
-.PHONY: dev build preview check-external
+.PHONY: dev build preview check-golden check-external
 
 define prepare-content
 	@test -d "$(CONTENT_PATH)" || (printf 'Content path does not exist: %s\n' "$(CONTENT_PATH)" >&2; exit 1)
@@ -23,7 +23,11 @@ preview:
 	$(MAKE) build CONTENT_PATH="$(CONTENT_PATH)" REPO_URL="$(REPO_URL)" BASE_PATH="$(BASE_PATH)" SITE_URL="$(SITE_URL)"
 	pnpm exec astro preview
 
+check-golden:
+	$(MAKE) build CONTENT_PATH="$(CURDIR)"
+	node scripts/verify-golden-build.mjs
+
 check-external:
 	$(MAKE) build CONTENT_PATH="$(CURDIR)/test-fixtures/external-consumer" REPO_URL="https://github.com/example/external-consumer"
-	@test -f dist/readme/index.html
+	@test -f dist/index.html
 	node scripts/verify-external-build.mjs

package/README.md

@@ -3,53 +3,73 @@ heading: Upcontent
 description: Turn a documentation repository into a fast, searchable, customizable static portal.
 ---
 
-Upcontent turns a Markdown repository into a documentation site that is ready to share.
+<div align="center">
 
-It is for software teams that already have documentation, but need a better way to publish it: clear navigation, search, useful rendering for technical content, consumer-owned branding, and a repeatable static build.
+# Upcontent
 
-## The short version
+**Turn the documentation repository you already have into a fast, searchable, customizable portal.**
 
-Upcontent gives a documentation repository:
+[![CI](https://github.com/lumamontes/upcontent/actions/workflows/ci.yml/badge.svg)](https://github.com/lumamontes/upcontent/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/upcontent?color=0f766e&label=npm)](https://www.npmjs.com/package/upcontent)
 
-- A responsive [Starlight](https://starlight.astro.build/) portal with navigation, search, themes, and table of contents
-- A `.upcontent/config.json` file for identity, navigation, rendering, and content boundaries
-- Custom CSS for the consumer's own brand
-- Rendered callouts, Mermaid diagrams, JSON, YAML, CSV, and wiki links
-- A static `dist/` directory that can be deployed to GitHub Pages or any static host
-- Build checks that catch broken wiki links and excluded content before publication
+<a href="https://lumamontes.github.io/upcontent/">See the live showcase</a> · <a href="#get-started">Get started in under a minute</a>
 
-The source repository remains the source of truth. Upcontent does not require a database, a companion server, or a new authoring system.
+</div>
 
-## Is this the right tool?
+## See the result
 
-Upcontent is a good fit when:
+This is the real Upcontent portal generated from this repository and deployed to GitHub Pages.
 
-- Your documentation already lives in Markdown or MDX.
-- Your team wants to keep writing in Git.
-- You want the portal to be owned and deployed by the documentation repository.
-- You need more than raw Markdown, but do not need a dynamic application.
-- You want branding and navigation without maintaining a custom docs frontend.
+<p align="center">
+  <a href="https://lumamontes.github.io/upcontent/"><img src="assets/readme/portal-home.png" alt="Upcontent documentation portal home page" width="900"></a>
+</p>
 
-It is not the right fit when your site needs runtime authentication, server-rendered personalization, or review comments inside the published portal.
+The same build includes a capability showcase for technical content, structured data, callouts, diagrams, navigation, and search.
 
-## Get started
+<p align="center">
+  <a href="https://lumamontes.github.io/upcontent/showcase/"><img src="assets/readme/portal-showcase.png" alt="Upcontent capability showcase page" width="900"></a>
+</p>
 
-### Publish an existing documentation repository
+## From repository to portal
 
-If your Markdown already lives in a GitHub repository, run the bootstrap command from that repository's root:
+Upcontent keeps your source of truth in Git and adds the publishing layer: clear navigation, full-text search, technical content rendering, consumer-owned branding, and a repeatable static build.
+
+If your Markdown already lives in a GitHub repository, the flow is:
 
 ```sh
 pnpm dlx upcontent init
 pnpm dlx upcontent dev
+pnpm dlx upcontent check
 ```
 
-The first command creates `.upcontent/` and a GitHub Pages workflow. The second starts a local portal using the repository you are already in. You do not need to clone the Upcontent renderer into your documentation repository.
+The first command creates `.upcontent/` and a GitHub Pages workflow. The second starts a local portal using the repository you are already in. The third builds the consumer portal and validates the generated site. You do not need to clone the Upcontent renderer into your documentation repository.
+
+Push the generated workflow and your documentation is published as a static site. The source repository remains the source of truth; Upcontent does not require a database, a companion server, or a new authoring system.
 
-See [Set up a consumer repository](getting-started/consumer-repository/) for the generated structure and configuration.
+## What you get
 
-### Explore this repository locally
+- A responsive [Starlight](https://starlight.astro.build/) portal with navigation, search, themes, and table of contents.
+- A `.upcontent/config.json` file for identity, navigation, rendering, and content boundaries.
+- Consumer-owned logos, favicon, CSS, site identity, and navigation.
+- Rendered callouts, Mermaid diagrams, JSON, YAML, CSV, and wiki links.
+- A static `dist/` directory deployable to GitHub Pages or any static host.
+- Build checks that catch broken wiki links and excluded content before publication.
 
-Clone this repository, then start the included golden consumer. This path is for exploring Upcontent itself:
+## Is it a good fit?
+
+Upcontent is a good fit when:
+
+- Your documentation already lives in Markdown or MDX.
+- Your team wants to keep writing in Git.
+- You want the portal to be owned and deployed by the documentation repository.
+- You need more than raw Markdown, but do not need a dynamic application.
+- You want branding and navigation without maintaining a custom docs frontend.
+
+It is not the right fit when your site needs runtime authentication, server-rendered personalization, or review comments inside the published portal.
+
+## Explore this repository locally
+
+Clone this repository, then start the included golden consumer:
 
 ```sh
 git clone https://github.com/lumamontes/upcontent.git
@@ -60,19 +80,26 @@ make dev CONTENT_PATH=.
 
 Then open the local URL printed by Astro. The [capability showcase](showcase/) is the fastest way to see the complete rendering and customization surface.
 
-The generated consumer configuration looks like this:
+## Configure your portal
+
+The consumer configuration is deliberately small:
 
 ```json
 {
   "site": {
     "title": "Engineering Docs",
     "description": "Documentation for the engineering team.",
+    "socialImage": "https://docs.example.com/social-card.png",
+    "locale": "en-US",
     "logo": {
       "src": ".upcontent/logo.svg",
       "alt": "Engineering Docs"
     },
     "favicon": ".upcontent/favicon.svg"
   },
+  "seo": {
+    "enabled": true
+  },
   "repo": {
     "url": "https://github.com/acme/engineering-docs"
   },
@@ -84,24 +111,13 @@ The generated consumer configuration looks like this:
 
 Follow [Set up a consumer repository](getting-started/consumer-repository/) for the complete setup, then use [Customization](customization/) to shape the portal.
 
-## See the full path
-
-- [First build](getting-started/first-build/): run the portal locally and generate static output.
-- [Consumer repository](getting-started/consumer-repository/): prepare content, assets, and configuration.
-- [Customization](customization/): configure identity, theme, navigation, content, JSON, and environment variables.
-- [Authoring content](guides/authoring-content/): write pages that are clear and easy to scan.
-- [Deployment](deployment/): publish the generated files to GitHub Pages or another static host.
-- [Capability showcase](showcase/): inspect all supported content and rendering features in one page.
-
 ## Build for production
 
 ```sh
 make build CONTENT_PATH=/path/to/your-consumer-repo
 ```
 
-The generated site is written to `dist/` and includes the Pagefind search index.
-
-Before publishing, run:
+The generated site is written to `dist/` and includes the Pagefind search index. Before publishing, run:
 
 ```sh
 pnpm test
@@ -110,6 +126,8 @@ make build CONTENT_PATH=.
 make check-external
 ```
 
+Read the [deployment guide](deployment/) for GitHub Pages and other static hosts.
+
 ## Built on Astro and Starlight
 
 Upcontent uses the official [Astro](https://astro.build/) framework and [Starlight](https://starlight.astro.build/) documentation theme as its rendering foundation. Upcontent adds the consumer-repository contract, content integrity checks, configuration surface, and deployment workflow around them.

package/astro.config.mjs

@@ -1,7 +1,8 @@
 import { fileURLToPath } from 'node:url'
-import { cpSync, existsSync, mkdirSync, statSync } from 'node:fs'
+import { cpSync, existsSync, mkdirSync, rmSync, statSync } from 'node:fs'
 import { basename, resolve, sep } from 'node:path'
 import { unified } from '@astrojs/markdown-remark'
+import sitemap from '@astrojs/sitemap'
 import starlight from '@astrojs/starlight'
 import { defineConfig } from 'astro/config'
 import { visit } from 'unist-util-visit'
@@ -9,13 +10,37 @@ import { rehypeCallouts } from './src/lib/rehype-callouts.ts'
 import { remarkStripDuplicateTitle } from './src/lib/remark-strip-duplicate-title.ts'
 import { remarkStructuredDataPreview } from './src/lib/remark-structured-data-preview.ts'
 import { remarkWikiLinks } from './src/lib/remark-wiki-links.ts'
+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))
 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()) {
+    for (const target of targets) rmSync(target, { force: true, recursive: true })
+    return
+  }
+
+  for (const target of targets) {
+    rmSync(target, { force: true, recursive: true })
+    mkdirSync(resolve(target, '..'), { recursive: true })
+    cpSync(source, target, { recursive: true })
+  }
+}
+
+copyContentAssetDirectory('assets/readme')
+
 function resolvePortalAsset(assetPath) {
   if (!assetPath || assetPath.startsWith('http')) return assetPath
   if (assetPath.startsWith('/')) return assetPath
@@ -58,6 +83,41 @@ const consumerCss = (portalConfig.theme?.customCss ?? [])
 
 const customCss = ['./src/styles/callouts.css', './src/styles/structured-data-preview.css', ...consumerCss]
 const starlightOptions = portalConfig.starlight ?? {}
+const noindexRoutes = getNoindexRoutes(docsRoot)
+const configuredSiteUrl = process.env.SITE_URL || portalConfig.site?.url
+let site
+let base = process.env.BASE_PATH || undefined
+if (portalConfig.seo?.enabled === true && configuredSiteUrl) {
+  try {
+    const parsedSiteUrl = new URL(configuredSiteUrl)
+    if (parsedSiteUrl.protocol !== 'http:' && parsedSiteUrl.protocol !== 'https:') throw new Error('unsupported protocol')
+    if (parsedSiteUrl.username || parsedSiteUrl.password) throw new Error('userinfo is not allowed')
+    site = parsedSiteUrl.origin
+    if (!process.env.BASE_PATH) base = parsedSiteUrl.pathname === '/' ? undefined : parsedSiteUrl.pathname
+  } catch {
+    console.warn(`[${PRODUCT_NAME}] SEO site URL must be an absolute URL: ${configuredSiteUrl}`)
+  }
+}
+
+function includeInSitemap(page) {
+  const pathname = new URL(page).pathname.replace(/\/+$/, '') || '/'
+  const basePath = (base || '').replace(/\/+$/, '')
+  const route = pathname === basePath
+    ? '/'
+    : basePath && pathname.startsWith(`${basePath}/`)
+      ? pathname.slice(basePath.length)
+      : pathname
+  return !noindexRoutes.has(route)
+}
+
+function serializeSitemapEntry(entry) {
+  if (!site) return entry
+  const homepageUrl = new URL(`${(base || '').replace(/\/+$/, '')}/`, site).href
+  if (entry.url === homepageUrl.replace(/\/$/, '') || entry.url === homepageUrl) {
+    return { ...entry, url: homepageUrl }
+  }
+  return entry
+}
 
 // Remark plugin: converts ```mermaid blocks to <div class="mermaid"> BEFORE Shiki runs
 function remarkMermaid() {
@@ -75,24 +135,12 @@ function remarkMermaid() {
   }
 }
 
-// Rehype plugin: strip .md suffix from internal hrefs so links resolve correctly
-function rehypeStripMdLinks() {
-  return (tree) => {
-    visit(tree, 'element', (node) => {
-      if (node.tagName !== 'a') return
-      const href = node.properties?.href
-      if (typeof href !== 'string') return
-      if (href.startsWith('http://') || href.startsWith('https://') || href.startsWith('#')) return
-      if (href.endsWith('.md')) node.properties.href = href.slice(0, -3)
-    })
-  }
-}
-
 export default defineConfig({
   output: 'static',
-  site: process.env.SITE_URL || portalConfig.site?.url || undefined,
-  base: process.env.BASE_PATH || undefined,
+  site,
+  base,
   integrations: [
+    sitemap({ filter: includeInSitemap, serialize: serializeSitemapEntry }),
     starlight({
       title: portalConfig.site?.title ?? PRODUCT_NAME,
       description: portalConfig.site?.description ?? PRODUCT_TAGLINE,
@@ -115,11 +163,12 @@ export default defineConfig({
     processor: unified({
       remarkPlugins: [
         remarkStripDuplicateTitle,
-        [remarkWikiLinks, { contentRoot: docsRoot, failOnBrokenLinks: true }],
+         [remarkWikiLinks, { contentRoot: docsRoot, basePath: base || '/', failOnBrokenLinks: true }],
+         [remarkDocumentLinks, { contentRoot: docsRoot, basePath: base || '/' }],
         remarkMermaid,
         remarkStructuredDataPreview,
       ],
-      rehypePlugins: [rehypeCallouts, rehypeStripMdLinks],
+      rehypePlugins: [rehypeCallouts],
     }),
   },
 })

package/customization/config-json.md

@@ -38,6 +38,8 @@ The optional fields below cover navigation, Starlight presentation, and content
     "title": "Engineering Docs",
     "description": "Documentation for the engineering team.",
     "url": "https://docs.example.com",
+    "socialImage": "https://docs.example.com/social-card.png",
+    "locale": "en-US",
     "logo": {
       "src": ".upcontent/logo.svg",
       "alt": "Engineering Docs",
@@ -45,6 +47,9 @@ The optional fields below cover navigation, Starlight presentation, and content
     },
     "favicon": ".upcontent/favicon.svg"
   },
+  "seo": {
+    "enabled": true
+  },
   "repo": {
     "url": "https://github.com/acme/engineering-docs"
   },
@@ -82,7 +87,8 @@ The optional fields below cover navigation, Starlight presentation, and content
 
 | Group | Controls |
 | --- | --- |
-| `site` | Name, description, URL, logo, and favicon. |
+| `site` | Name, description, URL, social image, locale, logo, and favicon. |
+| `seo` | Explicitly enables search-engine discoverability. Defaults to disabled. |
 | `repo` | Source repository links. |
 | `theme` | Consumer-owned local CSS. |
 | `starlight` | Safe layout, social, table of contents, pagination, and code options. |
@@ -90,3 +96,5 @@ The optional fields below cover navigation, Starlight presentation, and content
 | `content` | Frontmatter title field selection. |
 
 Invalid curated values are ignored or fall back safely. Heading levels must be integers from 1 through 6, and the minimum cannot exceed the maximum.
+
+SEO is opt-in. With `seo.enabled` omitted or set to `false`, the portal emits `noindex, nofollow` and `robots.txt` disallows crawling. This does not protect the site: use access-controlled hosting for a private portal.

package/customization/content.md

@@ -35,6 +35,20 @@ sidebar:
 
 Use `##` for body sections because the page title is rendered as the top-level heading.
 
+SEO-specific frontmatter is optional:
+
+```md
+---
+title: Configure a consumer repository
+description: Set up a documentation repository and publish it as a searchable portal.
+canonical: https://docs.example.com/getting-started/consumer-repository/
+image: https://docs.example.com/social-card.png
+noindex: false
+---
+```
+
+`description` is used in search and social metadata. `canonical`, `image`, and `noindex` override the generated defaults for that page. The site-level `socialImage` in `.upcontent/config.json` is used when a page does not define its own image.
+
 ## Supported content features
 
 - Obsidian-style callouts for notes, tips, cautions, and dangers

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/deployment/index.md

@@ -11,6 +11,7 @@ Upcontent produces static files. The deployment job only needs to build the cont
 
 - [GitHub Pages](github-pages/): use the included workflow and repository settings.
 - [Other static hosts](static-hosts/): publish `dist/` to Netlify, Vercel, S3, or another file host.
+- [Release the npm package](npm/): publish versioned package releases through GitHub Actions.
 - [Environment variables](../customization/environment/): set the URL and base path for the host.
 
 ## Before publishing

package/deployment/npm.md

@@ -0,0 +1,39 @@
+---
+title: Release the npm package
+description: Publish versioned Upcontent releases through GitHub Actions and npm Trusted Publishing.
+sidebar:
+  order: 3
+---
+
+Upcontent publishes the `upcontent` package from version tags. Ordinary pushes to `main` run validation and deploy the documentation portal, but do not publish to npm.
+
+## Configure npm once
+
+On the [upcontent npm package](https://www.npmjs.com/package/upcontent), add a GitHub Actions Trusted Publisher with:
+
+- Organization or user: `lumamontes`
+- Repository: `upcontent`
+- Workflow filename: `publish.yml`
+- Allow direct `npm publish`
+
+Trusted Publishing uses short-lived GitHub OIDC credentials. No npm token is stored in GitHub Actions.
+
+## Release a version
+
+Choose the next semantic version, update `package.json`, and commit the change:
+
+```sh
+npm version patch --no-git-tag-version
+git add package.json
+git commit -m "release: v$(node -p "require('./package.json').version")"
+```
+
+Create and push the matching tag:
+
+```sh
+VERSION=$(node -p "require('./package.json').version")
+git tag -a "v$VERSION" -m "Release v$VERSION"
+git push origin main --follow-tags
+```
+
+The publish workflow verifies that the tag and package version match, runs the full validation contract, inspects the package contents, and publishes the package with npm provenance.

package/guides/validate-your-site.md

@@ -13,6 +13,7 @@ Use this checklist before opening a pull request or publishing a consumer reposi
 pnpm test
 pnpm check
 make build CONTENT_PATH=.
+make check-golden
 make check-external
 git diff --check
 ```
@@ -36,6 +37,10 @@ Open the pages listed in the [capability showcase](../showcase/) and check:
 - Callouts, Mermaid, JSON, YAML, and CSV examples render correctly.
 - The layout works at desktop and mobile widths.
 - The browser console has no required-asset errors.
+- Each indexable page has a useful title, description, canonical URL, and one top-level heading.
+- `dist/robots.txt` points to the generated sitemap.
+- The page source contains JSON-LD and uses the intended `SITE_URL` and `BASE_PATH`.
+- `seo.enabled` matches the intended portal policy; disabled SEO must produce `noindex, nofollow` and `Disallow: /`.
 
 ## Check content boundaries
 

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.