upcontent 0.0.0-stage → 0.1.0

package/deployment/github-pages.md

@@ -0,0 +1,46 @@
+---
+title: GitHub Pages
+description: Publish a consumer repository through the reference GitHub Actions workflow.
+sidebar:
+  order: 2
+---
+
+The reusable Upcontent workflow builds the consumer repository and uploads `dist/` to GitHub Pages. Run `pnpm dlx upcontent init` in the consumer repository to generate the caller workflow.
+
+## Enable Pages
+
+1. Open the repository's **Settings > Pages**.
+2. Set the source to **GitHub Actions**.
+3. Confirm the workflow has `contents: read`, `pages: write`, and `id-token: write` permissions.
+4. Push to `main` or run the deployment workflow manually.
+
+## Configure the site URL
+
+A project site normally needs a base path:
+
+```yaml
+env:
+  BASE_PATH: /engineering-docs
+  SITE_URL: https://acme.github.io/engineering-docs
+```
+
+A custom domain normally uses an empty base path:
+
+```yaml
+env:
+  BASE_PATH: ''
+  SITE_URL: https://docs.acme.com
+```
+
+Read [Environment variables](../customization/environment/) before changing these values.
+
+## Verify the published site
+
+After deployment, open the published URL and check:
+
+- The header logo and favicon load.
+- Internal links include the correct base path.
+- Search returns results.
+- Light and dark themes work.
+- Mermaid, callouts, and structured previews render.
+- The browser console has no required-asset errors.

package/deployment/index.md

@@ -0,0 +1,24 @@
+---
+title: Deployment
+description: Publish the generated static portal to GitHub Pages or another static host.
+sidebar:
+  order: 1
+---
+
+Upcontent produces static files. The deployment job only needs to build the content and upload `dist/` to a host that serves HTML, CSS, JavaScript, and assets.
+
+## Choose a path
+
+- [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.
+- [Environment variables](../customization/environment/): set the URL and base path for the host.
+
+## Before publishing
+
+```sh
+pnpm test
+pnpm check
+make build CONTENT_PATH=/path/to/your-consumer-repo
+```
+
+Then confirm that `dist/` contains the generated pages and Pagefind assets.

package/deployment/static-hosts.md

@@ -0,0 +1,34 @@
+---
+title: Other static hosts
+description: Publish dist to a static hosting provider of your choice.
+sidebar:
+  order: 3
+---
+
+The output of `make build` is portable. Upload the contents of `dist/` to any host that serves static files.
+
+## Generic flow
+
+```sh
+make build CONTENT_PATH=/path/to/your-consumer-repo
+upload dist/ to your hosting provider
+```
+
+Set `SITE_URL` when the host supports canonical URLs or sitemap generation. Set `BASE_PATH` when the site is served below the domain root.
+
+## Separate portal and content repositories
+
+A CI job can check out both repositories before building:
+
+```text
+checkout the portal repository
+checkout the consumer repository
+make build CONTENT_PATH=/workspace/consumer
+upload dist/
+```
+
+The consumer checkout provides Markdown, `.upcontent/config.json`, assets, and CSS. The portal checkout provides the renderer and validation pipeline.
+
+## Privacy
+
+A private source repository does not make a public static host private. Use a host with access controls when the published site must be restricted.

package/getting-started/consumer-repository.md

@@ -0,0 +1,156 @@
+---
+title: Set up a consumer repository
+description: Prepare a documentation repository to be rendered by Upcontent.
+sidebar:
+  order: 2
+---
+
+A consumer repository is the source of truth for a published portal. It contains the documentation and the `.upcontent/` directory that describes the consumer's identity and presentation.
+
+Upcontent itself is also a GitHub repository. This project uses the same consumer contract described here: the repository root is the golden consumer, while `src/` contains the renderer.
+
+## This site as an example
+
+The repository behind this site keeps the renderer and its golden consumer together:
+
+```text
+upcontent/
+├── .upcontent/
+│   ├── config.json
+│   ├── favicon.svg
+│   ├── logo.svg
+│   └── portal.css
+├── README.md
+├── getting-started/
+├── guides/
+├── customization/
+├── deployment/
+├── SHOWCASE.mdx
+├── package.json
+└── .github/workflows/
+```
+
+The public pages are Markdown or MDX files in the repository root. The renderer implementation lives separately under `src/`; it is not part of the published sidebar. A separate consumer repository only needs its own documentation and `.upcontent/` directory.
+
+This site's actual `.upcontent/config.json` uses the same fields available to consumers:
+
+```json
+{
+  "site": {
+    "title": "Upcontent",
+    "description": "Create a beautiful, customizable Starlight portal from your documentation repository.",
+    "url": "https://lumamontes.github.io/upcontent",
+    "logo": {
+      "src": ".upcontent/logo.svg",
+      "alt": "",
+      "replacesTitle": false
+    },
+    "favicon": ".upcontent/favicon.svg"
+  },
+  "repo": {
+    "url": "https://github.com/lumamontes/upcontent"
+  },
+  "theme": {
+    "customCss": [".upcontent/portal.css"]
+  },
+  "starlight": {
+    "lastUpdated": true,
+    "pagination": true
+  }
+}
+```
+
+The filename is `.upcontent/config.json`; `portal.json` is not part of the current contract.
+
+## Recommended structure
+
+```text
+my-consumer-repo/
+├── .upcontent/
+│   ├── config.json
+│   ├── favicon.svg
+│   ├── logo.svg
+│   └── theme.css
+├── getting-started/
+│   └── first-page.md
+├── guides/
+│   └── operating-the-system.md
+└── README.md
+```
+
+The structure is a recommendation, not a requirement. Existing repositories can keep their current folders and use `navigation.roots` and `navigation.labelOverrides` to shape the sidebar.
+
+## Add the Upcontent configuration
+
+Create `.upcontent/config.json`:
+
+```json
+{
+  "site": {
+    "title": "Engineering Docs",
+    "description": "Documentation for the engineering team.",
+    "logo": {
+      "src": ".upcontent/logo.svg",
+      "alt": "Engineering Docs"
+    },
+    "favicon": ".upcontent/favicon.svg"
+  },
+  "repo": {
+    "url": "https://github.com/acme/engineering-docs"
+  },
+  "theme": {
+    "customCss": [".upcontent/theme.css"]
+  }
+}
+```
+
+Relative asset paths resolve from the consumer repository. Absolute URLs are also supported for externally hosted assets.
+
+See the [capability showcase](../../showcase/) and [configuration reference](../../customization/config-json/) for the supported options.
+
+## Bootstrap with the CLI
+
+From the consumer repository root:
+
+```sh
+pnpm dlx upcontent init
+```
+
+This creates the `.upcontent/` directory and a GitHub Pages workflow. The command preserves existing files and asks you to use `--force` before replacing generated files.
+
+Preview the repository locally before publishing:
+
+```sh
+pnpm dlx upcontent dev
+```
+
+## Choose the content root
+
+Use the consumer repository itself:
+
+```sh
+make dev CONTENT_PATH=/path/to/my-consumer-repo
+```
+
+For separate portal and content repositories, check out both repositories in the workflow and pass the content checkout as `CONTENT_PATH`.
+
+## Keep internal material private from navigation
+
+The portal always excludes its protected internal paths. Add consumer-specific paths with `navigation.blocklist`:
+
+```json
+{
+  "navigation": {
+    "blocklist": {
+      "exact": ["notes.md"],
+      "prefixes": ["drafts/", "internal/"]
+    }
+  }
+}
+```
+
+Blocklisted files are excluded before content parsing. They do not become pages or sidebar links.
+
+:::caution
+Blocklisting is a build-time content boundary, not an access-control system. Do not publish secrets or rely on a public static host to protect a private document.
+:::

package/getting-started/first-build.md

@@ -0,0 +1,78 @@
+---
+title: Your first build
+description: Run Upcontent locally and understand what it generates.
+sidebar:
+  order: 1
+---
+
+This guide takes you from a cloned Upcontent repository to a local documentation portal. If you have not cloned it yet:
+
+```sh
+git clone https://github.com/lumamontes/upcontent.git
+cd upcontent
+```
+
+## What you need
+
+- Node.js supported by the repository toolchain
+- pnpm
+- A documentation repository containing Markdown or MDX files
+
+Install dependencies from the portal repository:
+
+```sh
+pnpm install
+```
+
+## Start the portal locally
+
+Point `CONTENT_PATH` at the documentation repository you want to preview:
+
+```sh
+make dev CONTENT_PATH=.
+```
+
+Open the local URL printed by Astro. Changes to content and consumer configuration are reflected by the development server.
+
+## Build the static site
+
+Build the same consumer without a development server:
+
+```sh
+make build CONTENT_PATH=.
+```
+
+The generated site is written to `dist/`. It contains HTML, assets, and the Pagefind search index. Preview the generated output with:
+
+```sh
+pnpm exec astro preview
+```
+
+## Explore the example
+
+Start with these pages:
+
+- [Capability showcase](../../showcase/) shows rendering, content, customization, and workflows in one place.
+- [Authoring content](../../guides/authoring-content/) explains the writing conventions used here.
+- [Validate your site](../../guides/validate-your-site/) is the repeatable acceptance checklist.
+
+## Use another consumer repository
+
+The portal can render content from a different directory without copying it into this repository:
+
+```sh
+make dev CONTENT_PATH=/path/to/my-consumer-repo
+```
+
+The consumer repository owns its Markdown, `.upcontent/config.json`, assets, and custom CSS. The portal repository owns the renderer and validation pipeline.
+
+:::tip[The important boundary]
+Treat `CONTENT_PATH` as the product boundary. If a change only works when files are added to the portal implementation, it is not yet a consumer customization.
+:::
+
+## Next steps
+
+1. Read [Set up a consumer repository](../consumer-repository/).
+2. Add or review the consumer configuration in `.upcontent/config.json`.
+3. Follow [Authoring content](../../guides/authoring-content/) before adding new pages.
+4. Run [Validate your site](../../guides/validate-your-site/).

package/guides/authoring-content.md

@@ -0,0 +1,105 @@
+---
+title: Authoring content
+description: Write clear, navigable Markdown for a static Starlight portal.
+sidebar:
+  order: 1
+---
+
+Good documentation is task-oriented, explicit about its audience, and easy to scan. This guide describes the conventions used in a clear technical documentation site.
+
+## Start with the reader's task
+
+Prefer a page title that completes the sentence "I want to...":
+
+- Good: `Configure a consumer repository`
+- Weak: `Configuration`
+
+Open with one or two sentences that explain the outcome. Put prerequisites before the first action. Keep each section focused on one decision or step.
+
+## Use frontmatter deliberately
+
+Every page can declare metadata at the top of the file:
+
+```md
+---
+title: Configure a consumer repository
+sidebar:
+  order: 2
+---
+```
+
+The title becomes the page heading and the default sidebar label. The description is used for page metadata and search context. Use `sidebar.order` only when ordering carries meaning; otherwise let the portal sort pages consistently.
+
+## Structure headings for scanning
+
+The page title is the top-level heading generated by Starlight. Start body sections at `##`:
+
+```md
+## Before you begin
+
+## Configure the repository
+
+### Add the portal configuration
+
+### Verify the result
+```
+
+Short sections, descriptive headings, and lists help readers find the answer without reading every paragraph.
+
+## Show commands in context
+
+Use a language tag and explain what the reader should observe:
+
+```sh
+make build CONTENT_PATH=.
+```
+
+Do not show commands without saying where to run them, what they change, or how to verify the result. Use placeholders for values that readers must replace:
+
+```sh
+make dev CONTENT_PATH=/path/to/your-consumer-repo
+```
+
+## Link to stable concepts
+
+Use normal Markdown links for known pages. Use wiki links when the source repository needs filename-oriented references:
+
+```md
+[Validate your site](../guides/validate-your-site/)
+[Capability showcase](../showcase/)
+```
+
+Wiki links must resolve to a document. The build fails when a target is missing, so a typo cannot silently become published broken navigation.
+
+## Use callouts for decisions
+
+Callouts should contain short, consequential information:
+
+:::tip[Prefer the smallest change]
+Start with consumer configuration and CSS tokens before adding implementation code.
+:::
+
+:::caution
+Static output is public wherever the selected host is public. Repository privacy does not automatically make the published portal private.
+:::
+
+Avoid turning every paragraph into a callout. If everything is highlighted, nothing is prioritized.
+
+## Make examples executable
+
+The showcase uses real examples for Mermaid, JSON, YAML, CSV, callouts, and palette switching. Prefer examples that can be built and inspected over decorative snippets that are never exercised.
+
+When an example depends on a file, keep that file in the repository and include the validation command in the surrounding text.
+
+## Content review checklist
+
+Before publishing a page, check:
+
+- The title describes the reader's outcome.
+- The first paragraph explains why the page exists.
+- Prerequisites appear before actions.
+- Headings begin at `##` in the body.
+- Commands include their working directory and expected result.
+- Links use stable page paths and wiki links resolve.
+- Warnings explain a real risk rather than adding visual noise.
+- The page was built and inspected at desktop and mobile widths.

package/guides/validate-your-site.md

@@ -0,0 +1,53 @@
+---
+title: Validate your site
+description: Check content, configuration, generated output, and browser behavior before publishing.
+sidebar:
+  order: 2
+---
+
+Use this checklist before opening a pull request or publishing a consumer repository.
+
+## Run the build contract
+
+```sh
+pnpm test
+pnpm check
+make build CONTENT_PATH=.
+make check-external
+git diff --check
+```
+
+The tests cover content loading, title fallback, navigation, blocklists, wiki links, callouts, Mermaid transformation, and structured previews. The external build confirms that a separate consumer repository works too.
+
+## Check the browser
+
+Start the portal locally:
+
+```sh
+make dev CONTENT_PATH=.
+```
+
+Open the pages listed in the [capability showcase](../showcase/) and check:
+
+- The logo appears once and the site name is clear.
+- The sidebar groups are understandable and the active page is easy to find.
+- Search, internal links, and the table of contents work.
+- Light and dark themes remain readable.
+- 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.
+
+## Check content boundaries
+
+The build should not publish:
+
+- `.upcontent/` files
+- Protected repository internals
+- Consumer blocklisted paths
+- Documents with malformed or traversal wiki links
+
+When a change affects blocklists or navigation roots, verify both the generated route list and the sidebar. Hiding a link is not enough; excluded content must be absent before parsing.
+
+## Record the result
+
+If a check fails, record the source page, route, and browser or build output in the relevant engineering ticket. Do not mark a documentation change complete based only on a successful local page load.

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "upcontent",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "type": "module",
+  "version": "0.1.0",
+  "bin": {
+    "upcontent": "scripts/upcontent-cli.mjs"
+  },
+  "dependencies": {
+    "@astrojs/markdown-remark": "^7.3.1",
+    "@astrojs/starlight": "^0.42.1",
+    "@fontsource/poppins": "^5.3.0",
+    "astro": "^7.3.3",
+    "js-yaml": "^4.3.2",
+    "mermaid": "^11.0.0",
+    "papaparse": "^5.7.0",
+    "unist-util-visit": "^5.0.0",
+    "zod": "^3.0.0"
+  },
+  "devDependencies": {
+    "@astrojs/check": "^0.9.10",
+    "@types/js-yaml": "^4.0.9",
+    "@types/papaparse": "^5.5.2",
+    "rehype-stringify": "^10.0.1",
+    "remark-parse": "^11.0.0",
+    "remark-rehype": "^11.1.2",
+    "typescript": "^5.0.0",
+    "unified": "^11.0.5",
+    "vitest": "^2.0.0"
+  },
+  "scripts": {
+    "dev": "astro dev",
+    "build": "astro build",
+    "check": "astro check",
+    "test": "vitest run"
+  }
 }

package/scripts/upcontent-cli.mjs

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { spawnSync } from 'node:child_process'
+
+const command = process.argv[2] ?? 'help'
+const force = process.argv.includes('--force')
+const root = process.cwd()
+const rendererRoot = dirname(dirname(fileURLToPath(import.meta.url)))
+
+const config = `{
+  "site": {
+    "title": "Documentation",
+    "description": "Project documentation.",
+    "logo": {
+      "src": ".upcontent/logo.svg",
+      "alt": "Documentation"
+    },
+    "favicon": ".upcontent/favicon.svg"
+  },
+  "repo": {
+    "url": "https://github.com/ORG/REPOSITORY"
+  },
+  "theme": {
+    "customCss": [".upcontent/theme.css"]
+  }
+}
+`
+
+const theme = `:root {
+  --sl-color-accent: #0f766e;
+  --sl-color-accent-high: #115e59;
+}
+`
+
+const logo = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 72 72">
+  <rect width="56" height="56" x="8" y="8" rx="16" fill="#0f766e"/>
+  <path d="M20 24h32v8H20zm0 16h24v8H20z" fill="#fff"/>
+</svg>
+`
+
+const favicon = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64">
+  <rect width="64" height="64" rx="16" fill="#0f766e"/>
+  <path d="M18 20h28v8H18zm0 16h21v8H18z" fill="#fff"/>
+</svg>
+`
+
+const workflow = `name: Publish documentation
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  publish:
+     uses: lumamontes/upcontent/.github/workflows/reusable-pages.yml@main
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+`
+
+function init() {
+  const files = [
+    ['.upcontent/config.json', config],
+    ['.upcontent/theme.css', theme],
+    ['.upcontent/logo.svg', logo],
+    ['.upcontent/favicon.svg', favicon],
+    ['.github/workflows/deploy-docs.yml', workflow],
+  ]
+  const collisions = files.filter(([relativePath]) => existsSync(join(root, relativePath)))
+  if (collisions.length > 0 && !force) {
+    for (const [relativePath] of collisions) {
+      console.error(`Refusing to overwrite ${relativePath}. Use --force to replace generated files.`)
+    }
+    process.exitCode = 1
+    return
+  }
+  for (const [relativePath, content] of files) {
+    const absolutePath = join(root, relativePath)
+    mkdirSync(dirname(absolutePath), { recursive: true })
+    writeFileSync(absolutePath, content)
+    console.log(`created ${relativePath}`)
+  }
+  console.log('\nNext steps:')
+  console.log('1. Replace ORG/REPOSITORY in .upcontent/config.json.')
+  console.log('2. Review the generated identity and theme files.')
+  console.log('3. Run `pnpm dlx upcontent dev` to preview locally.')
+  console.log('4. Push to main to publish through GitHub Actions.')
+}
+
+function run(name, args) {
+  const result = spawnSync(name, args, { cwd: rendererRoot, stdio: 'inherit' })
+  if (result.error) throw result.error
+  return result.status === 0
+}
+
+if (command === 'init') init()
+else if (command === 'dev') {
+  process.exitCode = run('make', ['dev', `CONTENT_PATH=${root}`]) ? 0 : 1
+}
+else if (command === 'check') {
+  const passed = run('pnpm', ['test'])
+    && run('pnpm', ['check'])
+    && run('make', ['build', `CONTENT_PATH=${root}`])
+  process.exitCode = passed ? 0 : 1
+}
+else {
+  console.log('Usage: upcontent <init|dev|check> [--force]')
+}

package/scripts/verify-external-build.mjs

@@ -0,0 +1,24 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+
+const html = readFileSync('dist/readme/index.html', 'utf8')
+const required = [
+  'External Consumer',
+  'https://github.com/example/external-consumer',
+  '/upcontent-assets/favicon.svg',
+]
+
+for (const value of required) {
+  if (!html.includes(value)) throw new Error(`External consumer artifact is missing: ${value}`)
+}
+
+if (!existsSync('dist/upcontent-assets/favicon.svg')) throw new Error('External consumer favicon was not copied')
+if (!html.includes('alt="External Consumer"')) throw new Error('External consumer logo was not rendered')
+if (existsSync('dist/forbidden/index.html')) throw new Error('External consumer blocklist leaked forbidden.md')
+if (existsSync('dist/upcontent-renderer/readme/index.html')) {
+  throw new Error('External consumer build leaked renderer checkout content')
+}
+if (!existsSync('dist/pagefind/pagefind.js')) throw new Error('External consumer Pagefind output is missing')
+
+const cssFiles = readdirSync('dist/_astro').filter(file => file.endsWith('.css'))
+const hasConsumerCss = cssFiles.some(file => readFileSync(`dist/_astro/${file}`, 'utf8').includes('#0f766e'))
+if (!hasConsumerCss) throw new Error('External consumer CSS was not included')