upcontent 0.0.0-stage → 0.1.0

package/.github/workflows/ci.yml

@@ -0,0 +1,61 @@
+name: Validate portal
+
+on:
+  pull_request:
+  push:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: validate-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+
+      - 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: 22
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Run tests
+        run: pnpm test
+
+      - name: Run Astro diagnostics
+        run: pnpm check
+
+      - name: Build golden consumer
+        run: make build CONTENT_PATH=.
+
+      - name: Check golden artifact
+        run: |
+          test -f dist/index.html
+          test -f dist/pagefind/pagefind.js
+          test -f dist/upcontent-assets/favicon.svg
+
+      - name: Build external consumer fixture
+        run: make check-external
+
+      - name: Check diff hygiene
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha || github.event.before }}
+        run: |
+          git diff --check "$BASE_SHA" HEAD
+          git diff --exit-code
+          test -z "$(git status --porcelain --untracked-files=all)"

package/.github/workflows/deploy.yml

@@ -0,0 +1,59 @@
+name: Deploy documentation portal
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v5
+
+      - name: Set up Pages
+        id: pages
+        uses: actions/configure-pages@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: 22
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build static portal
+        run: make build CONTENT_PATH=. REPO_URL="https://github.com/${{ github.repository }}" BASE_PATH="${{ steps.pages.outputs.base_path }}" SITE_URL="${{ steps.pages.outputs.origin }}"
+
+      - name: Upload static artifact
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: dist
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

package/.github/workflows/reusable-pages.yml

@@ -0,0 +1,74 @@
+name: Reusable Upcontent Pages build
+
+on:
+  workflow_call:
+    inputs:
+      portal-repository:
+        description: Repository containing the Upcontent renderer.
+        required: false
+        type: string
+        default: lumamontes/upcontent
+      portal-ref:
+        description: Tag, branch, or commit of the Upcontent renderer.
+        required: false
+        type: string
+        default: main
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out consumer repository
+        uses: actions/checkout@v5
+
+      - name: Check out Upcontent renderer
+        uses: actions/checkout@v5
+        with:
+          repository: ${{ inputs.portal-repository }}
+          ref: ${{ inputs.portal-ref }}
+          path: .upcontent-renderer
+
+      - name: Set up Pages
+        id: pages
+        uses: actions/configure-pages@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: 22
+          cache: pnpm
+          cache-dependency-path: .upcontent-renderer/pnpm-lock.yaml
+
+      - name: Install renderer dependencies
+        working-directory: .upcontent-renderer
+        run: pnpm install --frozen-lockfile
+
+      - name: Build portal
+        working-directory: .upcontent-renderer
+        run: make build CONTENT_PATH="${{ github.workspace }}" REPO_URL="https://github.com/${{ github.repository }}" BASE_PATH="${{ steps.pages.outputs.base_path }}" SITE_URL="${{ steps.pages.outputs.origin }}"
+
+      - name: Upload static artifact
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: .upcontent-renderer/dist
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

package/.upcontent/config.json

@@ -0,0 +1,82 @@
+{
+  "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": {
+    "social": [
+      {
+        "icon": "github",
+        "label": "GitHub",
+        "href": "https://github.com/lumamontes/upcontent"
+      }
+    ],
+    "tableOfContents": {
+      "minHeadingLevel": 2,
+      "maxHeadingLevel": 3
+    },
+    "lastUpdated": true,
+    "pagination": true,
+    "expressiveCode": {
+      "styleOverrides": {
+        "borderRadius": "0.6rem"
+      }
+    }
+  },
+  "navigation": {
+    "roots": [
+      "README.md",
+      "getting-started",
+      "guides",
+      "customization",
+      "deployment",
+      "SHOWCASE.mdx"
+    ],
+    "blocklist": {
+      "prefixes": [
+        ".git/",
+        ".scratch/",
+        ".agents/",
+        ".claude/",
+        ".cursor/",
+        ".codex/",
+        ".opencode/",
+        "node_modules/",
+        "dist/",
+        ".astro/",
+        "src/",
+        "server/",
+        "docs/agents/",
+        "docs/",
+        "test-fixtures/",
+        "external-consumer/",
+        "workflows/"
+      ],
+      "exact": [
+        "AGENTS.md",
+        "CLAUDE.md",
+        "CONTEXT.md",
+        "PRODUCT.md"
+      ]
+    },
+    "labelOverrides": {
+      "docs": "Project Docs"
+    }
+  },
+  "content": {
+    "titleField": "heading"
+  }
+}

package/.upcontent/favicon.svg

@@ -0,0 +1,4 @@
+<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>

package/.upcontent/logo.svg

@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 72 72" role="img" aria-labelledby="title desc">
+  <title id="title">Upcontent</title>
+  <desc id="desc">Upcontent mark.</desc>
+  <rect width="56" height="56" x="8" y="8" rx="16" fill="#0f766e"/>
+  <path d="M20 24h32v8H20zm0 16h24v8H20z" fill="#fff"/>
+</svg>

package/.upcontent/portal.css

@@ -0,0 +1,139 @@
+@import '@fontsource/poppins/400.css';
+@import '@fontsource/poppins/500.css';
+@import '@fontsource/poppins/600.css';
+@import '@fontsource/poppins/700.css';
+
+/* The consumer owns this identity and can replace it without changing the renderer. */
+:root {
+  --sl-color-accent: #0f766e;
+  --sl-color-accent-high: #115e59;
+  --sl-color-accent-low: #ccfbf1;
+  --sl-color-text-accent: #0f766e;
+  --sl-color-bg: #f8faf7;
+  --sl-color-bg-nav: #f8faf7;
+  --sl-color-bg-sidebar: #eef4f1;
+  --sl-color-bg-inline-code: #e3eeea;
+  --sl-color-hairline-light: #d8e5df;
+  --sl-font: 'Poppins', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+  --sl-font-mono: 'SFMono-Regular', Consolas, monospace;
+  --sl-text-5xl: 3.35rem;
+  --sl-content-width: 48rem;
+  --sl-line-height: 1.72;
+  --up-sidebar-active: rgba(15, 118, 110, 0.08);
+  --up-sidebar-hover: rgba(15, 118, 110, 0.07);
+}
+
+:root[data-theme='light'] {
+  --sl-color-accent: #0f766e;
+  --sl-color-accent-high: #115e59;
+  --sl-color-accent-low: #ccfbf1;
+  --sl-color-text-accent: #0f766e;
+  --sl-color-bg: #f8faf7;
+  --sl-color-bg-nav: #f8faf7;
+  --sl-color-bg-sidebar: #eef4f1;
+  --sl-color-bg-inline-code: #e3eeea;
+  --sl-color-hairline-light: #d8e5df;
+  --up-sidebar-active: rgba(15, 118, 110, 0.08);
+  --up-sidebar-hover: rgba(15, 118, 110, 0.07);
+}
+
+:root[data-theme='dark'] {
+  --sl-color-accent: #5eead4;
+  --sl-color-accent-high: #99f6e4;
+  --sl-color-accent-low: #134e4a;
+  --sl-color-text-accent: #99f6e4;
+  --sl-color-bg: #0d191a;
+  --sl-color-bg-nav: #102324;
+  --sl-color-bg-sidebar: #0f2021;
+  --sl-color-bg-inline-code: #173334;
+  --sl-color-hairline-light: #274445;
+  --up-sidebar-active: rgba(94, 234, 212, 0.09);
+  --up-sidebar-hover: rgba(94, 234, 212, 0.08);
+}
+
+.site-title {
+  font-size: 1.15rem;
+  font-weight: 600;
+  letter-spacing: -0.025em;
+}
+
+.sl-container > h1,
+.sl-markdown-content h1 {
+  font-weight: 600;
+  letter-spacing: -0.035em;
+}
+
+.sl-markdown-content h2 {
+  margin-top: 2.6em;
+  padding-top: 0.7em;
+  border-top: 1px solid var(--sl-color-hairline-light);
+  letter-spacing: -0.035em;
+}
+
+.sl-markdown-content :not(pre) > code {
+  border: 1px solid var(--sl-color-hairline-light);
+  border-radius: 0.25rem;
+  padding: 0.12em 0.35em;
+}
+
+.sl-markdown-content blockquote {
+  border-inline-start-color: var(--sl-color-accent);
+}
+
+.header {
+  border-bottom: 1px solid var(--sl-color-hairline-light);
+}
+
+.sl-markdown-content a:not(.sl-link-button) {
+  text-decoration-thickness: 0.08em;
+  text-underline-offset: 0.18em;
+}
+
+.sidebar-content .top-level > li + li {
+  margin-top: 0.3rem;
+}
+
+.sidebar-content .top-level > li > details > summary {
+  color: var(--sl-color-text);
+  font-weight: 600;
+  letter-spacing: 0.005em;
+  padding-block: 0.35rem;
+}
+
+.sidebar-content .top-level > li > details > summary .caret {
+  color: var(--sl-color-gray-3);
+}
+
+.sidebar-content ul ul {
+  margin-top: 0.2rem;
+}
+
+.sidebar-content ul ul li {
+  border-inline-start-color: var(--sl-color-hairline-light);
+}
+
+.sidebar-content a {
+  border-radius: 0.45rem;
+  padding-block: 0.42rem;
+  transition: background-color 140ms ease, color 140ms ease;
+}
+
+.sidebar-content a:hover,
+.sidebar-content a:focus-visible {
+  background: var(--up-sidebar-hover);
+  color: var(--sl-color-text);
+}
+
+.sidebar-content a[aria-current='page'],
+.sidebar-content a[aria-current='page']:hover,
+.sidebar-content a[aria-current='page']:focus-visible {
+  background: var(--up-sidebar-active);
+  color: var(--sl-color-text-accent);
+  font-weight: 600;
+}
+
+@media (min-width: 50em) {
+  .sl-markdown-content h1 {
+    max-width: 15ch;
+  }
+}

package/Makefile

@@ -0,0 +1,29 @@
+CONTENT_PATH ?= $(HOME)/www/my-content-repo
+REPO_URL ?=
+BASE_PATH ?=
+SITE_URL ?=
+
+.PHONY: dev build preview check-external
+
+define prepare-content
+	@test -d "$(CONTENT_PATH)" || (printf 'Content path does not exist: %s\n' "$(CONTENT_PATH)" >&2; exit 1)
+	@rm -f src/content/docs
+	@ln -s "$(abspath $(CONTENT_PATH))" src/content/docs
+endef
+
+dev:
+	$(prepare-content)
+	REPO_URL=$(REPO_URL) BASE_PATH=$(BASE_PATH) SITE_URL=$(SITE_URL) pnpm exec astro dev
+
+build:
+	$(prepare-content)
+	REPO_URL=$(REPO_URL) BASE_PATH=$(BASE_PATH) SITE_URL=$(SITE_URL) pnpm exec astro build
+
+preview:
+	$(MAKE) build CONTENT_PATH="$(CONTENT_PATH)" REPO_URL="$(REPO_URL)" BASE_PATH="$(BASE_PATH)" SITE_URL="$(SITE_URL)"
+	pnpm exec astro preview
+
+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
+	node scripts/verify-external-build.mjs

package/README.md

@@ -1,3 +1,115 @@
-# Temporary Holding Version
+---
+heading: Upcontent
+description: Turn a documentation repository into a fast, searchable, customizable static portal.
+---
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Upcontent turns a Markdown repository into a documentation site that is ready to share.
+
+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.
+
+## The short version
+
+Upcontent gives a documentation repository:
+
+- 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
+
+The source repository remains the source of truth. Upcontent does not require a database, a companion server, or a new authoring system.
+
+## Is this the right tool?
+
+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.
+
+## Get started
+
+### Publish an existing documentation repository
+
+If your Markdown already lives in a GitHub repository, run the bootstrap command from that repository's root:
+
+```sh
+pnpm dlx upcontent init
+pnpm dlx upcontent dev
+```
+
+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.
+
+See [Set up a consumer repository](getting-started/consumer-repository/) for the generated structure and configuration.
+
+### Explore this repository locally
+
+Clone this repository, then start the included golden consumer. This path is for exploring Upcontent itself:
+
+```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.
+
+The generated consumer configuration looks like this:
+
+```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"]
+  }
+}
+```
+
+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:
+
+```sh
+pnpm test
+pnpm check
+make build CONTENT_PATH=.
+make check-external
+```
+
+## 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.