upcontent 0.0.0-stage → 0.1.1

package/customization/index.md

@@ -0,0 +1,33 @@
+---
+title: Customization
+description: Configure the portal from the consumer repository without editing the renderer.
+sidebar:
+  order: 1
+---
+
+Customization belongs to the consumer repository. The renderer stays shared; the consumer decides what the site is called, how it looks, what appears in navigation, and where it is published.
+
+## Choose a path
+
+- [Site identity](site-identity/): title, description, logo, favicon, and repository links.
+- [Theme and CSS](theme/): colors, typography, spacing, and dark mode using Starlight tokens.
+- [Navigation](navigation/): sidebar roots, labels, and content blocklists.
+- [Content behavior](content/): title fields, page metadata, and supported rendered content.
+- [JSON configuration](config-json/): the complete `.upcontent/config.json` guide.
+- [Environment variables](environment/): build-time values for repository URLs and hosting paths.
+
+The [configuration reference](config-json/) is the source of truth for supported fields. The [capability showcase](../showcase/) demonstrates the result in one page.
+
+## The customization boundary
+
+Consumer-owned files normally live here:
+
+```text
+.upcontent/
+├── config.json
+├── favicon.svg
+├── logo.svg
+└── theme.css
+```
+
+If a customization requires changing `astro.config.mjs`, it is not part of the normal consumer configuration surface.

package/customization/navigation.md

@@ -0,0 +1,57 @@
+---
+title: Navigation
+description: Shape the sidebar and keep internal material out of the published portal.
+sidebar:
+  order: 4
+---
+
+The sidebar is generated from the consumer file structure. Use configuration when the default filesystem order is not the right experience for readers.
+
+## Select top-level roots
+
+```json
+{
+  "navigation": {
+    "roots": [
+      "README.md",
+      "getting-started",
+      "guides",
+      "reference"
+    ]
+  }
+}
+```
+
+`roots` limits the files and folders shown at the top level. It does not move files or change their URLs.
+
+## Rename generated labels
+
+```json
+{
+  "navigation": {
+    "labelOverrides": {
+      "api": "API reference",
+      "runbooks": "Runbooks"
+    }
+  }
+}
+```
+
+Keys are matched case-insensitively. Use labels that describe the reader's destination, not the team's internal shorthand.
+
+## Exclude content before parsing
+
+```json
+{
+  "navigation": {
+    "blocklist": {
+      "exact": ["notes.md"],
+      "prefixes": ["drafts/", "internal/"]
+    }
+  }
+}
+```
+
+Blocklisted paths are excluded from the content collection and sidebar before Markdown is parsed. The portal also protects internal paths such as `.upcontent/`, `.github/`, `src/`, and `node_modules/`.
+
+Blocklisting is not access control. Do not put secrets in a repository that will be published to a public host.

package/customization/site-identity.md

@@ -0,0 +1,43 @@
+---
+title: Site identity
+description: Give a consumer portal its own name, assets, and repository links.
+sidebar:
+  order: 2
+---
+
+The consumer controls the visible identity of the published portal.
+
+## Configuration
+
+```json
+{
+  "site": {
+    "title": "Engineering Docs",
+    "description": "Documentation for the engineering team.",
+    "url": "https://docs.example.com",
+    "logo": {
+      "src": ".upcontent/logo.svg",
+      "alt": "Engineering Docs",
+      "replacesTitle": false
+    },
+    "favicon": ".upcontent/favicon.svg"
+  },
+  "repo": {
+    "url": "https://github.com/acme/engineering-docs"
+  }
+}
+```
+
+## Logo behavior
+
+Use a compact logo mark when the header should display the site title beside it. Set `replacesTitle` to `true` when the logo already contains the full wordmark.
+
+Always provide useful alternative text when the logo communicates identity. Use an empty `alt` when the adjacent visible site title already provides the accessible name.
+
+Relative asset paths resolve from the consumer repository. Logo and favicon assets are copied into the static output during the build.
+
+## Repository links
+
+`repo.url` powers links that let readers view or edit the source document on GitHub. Set it to the repository containing the content, not the repository containing the shared portal renderer.
+
+If the content repository is private, confirm that the links are appropriate for the readers who will receive the published site.

package/customization/theme.md

@@ -0,0 +1,47 @@
+---
+title: Theme and CSS
+description: Customize color, typography, and spacing with the official Starlight CSS seam.
+sidebar:
+  order: 3
+---
+
+Use `theme.customCss` to refine the Starlight surface without replacing its layout or accessibility behavior.
+
+## Load a consumer stylesheet
+
+```json
+{
+  "theme": {
+    "customCss": [".upcontent/theme.css"]
+  }
+}
+```
+
+The path is relative to the consumer repository. CSS is bundled during the build, so keep the stylesheet in the content repository rather than depending on a remote stylesheet.
+
+## Use Starlight tokens
+
+```css
+:root {
+  --sl-color-accent: #0f766e;
+  --sl-color-accent-high: #115e59;
+  --sl-font: 'Poppins', sans-serif;
+}
+
+:root[data-theme='dark'] {
+  --sl-color-accent: #5eead4;
+  --sl-color-accent-high: #99f6e4;
+}
+```
+
+Tokens keep custom colors aligned with callouts, links, code blocks, and theme switching.
+
+## Keep the interface coherent
+
+- Define both light and dark values for strong colors.
+- Prefer tokens over hard-coded colors in component selectors.
+- Keep body text readable before adjusting decorative styles.
+- Use one display or body family consistently instead of styling every section differently.
+- Check keyboard focus and reduced-motion behavior after adding transitions.
+
+The site's stylesheet is a working example of this seam.

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,25 @@
+---
+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.
+- [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
+
+```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/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/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.