upcontent 0.0.0-stage → 0.1.1

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: Check golden artifact
+        run: make check-golden
+
+      - name: Check golden runtime assets
+        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/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/.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,85 @@
+{
+  "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"
+  },
+  "seo": {
+    "enabled": true
+  },
+  "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/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

@@ -0,0 +1,33 @@
+CONTENT_PATH ?= $(HOME)/www/my-content-repo
+REPO_URL ?=
+BASE_PATH ?=
+SITE_URL ?=
+
+.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)
+	@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-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/index.html
+	node scripts/verify-external-build.mjs