upcontent 0.1.3 → 0.1.5

package/.upcontent/config.json

@@ -78,7 +78,7 @@
     },
     "labelOverrides": {
       "docs": "Project Docs",
-      "readme": "Repository README"
+      "index": "Getting Started"
     }
   },
   "content": {

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"],

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

@@ -5,15 +5,137 @@ sidebar:
   order: 1
 ---
 
-Upcontent turns a Markdown repository into a documentation site that is ready to share.
+Upcontent turns the documentation repository you already have into a fast, searchable, customizable portal.
 
-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.
+[![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)
 
-## Start here
+## Explore Upcontent
 
+- [See the live portal](https://lumamontes.github.io/upcontent/)
+- [Explore the capability showcase](showcase/)
 - [Set up a consumer repository](getting-started/consumer-repository/)
 - [Run your first build](getting-started/first-build/)
+- [Configure content](customization/content/)
+- [Configure navigation](customization/navigation/)
 - [Customize the portal](customization/)
 - [Validate before publishing](guides/validate-your-site/)
+- [Publish to GitHub Pages](deployment/github-pages/)
+- [Publish to another static host](deployment/static-hosts/)
+- [Publish releases through npm](deployment/npm/)
 
-The [repository README](readme/) contains the project and development details for Upcontent itself.
+## See the result
+
+This is the real Upcontent portal generated from this repository and deployed to GitHub Pages.
+
+<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>
+
+The same build includes a capability showcase for technical content, structured data, callouts, diagrams, navigation, and search.
+
+<p align="center">
+  <a href="showcase/"><img src="assets/readme/portal-showcase.png" alt="Upcontent capability showcase page" width="900"></a>
+</p>
+
+## From repository to portal
+
+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. 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.
+
+## What you get
+
+- 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.
+
+## 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
+cd upcontent
+pnpm install
+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.
+
+## 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"
+  },
+  "theme": {
+    "customCss": [".upcontent/theme.css"]
+  }
+}
+```
+
+Follow [Set up a consumer repository](getting-started/consumer-repository/) for the complete setup, then use [Customization](customization/) to shape the portal.
+
+## 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:
+
+```sh
+pnpm test
+pnpm check
+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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "upcontent",
   "type": "module",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "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) {
@@ -113,10 +116,10 @@ export function buildSidebar(docsRoot: string): SidebarEntry[] {
     }
   }
 
-  // A homepage fica fixa em primeiro, com o label configurável "Home" por
-  // padrão, sem competir alfabeticamente com as outras páginas.
+  // A homepage fica fixa em primeiro, com o label configurável, 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 homepageEntry ? [{ slug: 'index', label: resolveLabel(homepage, 'Home') }, ...sorted] : sorted
+  return homepageEntry ? [{ slug: 'index', label: resolveLabel(homepage, 'Getting Started') }, ...sorted] : sorted
 }