upcontent 0.0.0-stage → 0.1.0

package/SHOWCASE.mdx

@@ -0,0 +1,163 @@
+---
+heading: Capability showcase
+description: One practical page showing what a consumer repository can render, configure, and publish with Upcontent.
+sidebar:
+  order: 1
+---
+
+import PaletteShowcase from './src/components/PaletteShowcase.astro';
+
+Upcontent turns Markdown into a searchable static documentation site. Configure the consumer repository, add the content formats your team needs, and publish the generated `dist/` directory to a static host.
+
+## Rendered content
+
+The portal accepts ordinary Markdown and adds a small set of useful content features.
+
+### Callouts
+
+:::tip[Use callouts for decisions]
+Keep callouts short. Use them for a warning, a recommendation, or a next action that should not disappear in the surrounding text.
+:::
+
+:::caution
+Static output is public wherever the selected host is public. A private source repository does not automatically make the published site private.
+:::
+
+### Code and diagrams
+
+```ts
+export function buildPortal(contentPath: string) {
+  return `make build CONTENT_PATH=${contentPath}`
+}
+```
+
+```mermaid
+flowchart LR
+  Content[Consumer repository] --> Config[.upcontent/config.json]
+  Config --> Build[Static build]
+  Content --> Build
+  Build --> Output[Searchable portal]
+```
+
+Mermaid diagrams support theme synchronization, fullscreen, zoom, pan, source copying, and an invalid-source fallback.
+
+### Structured examples
+
+JSON and YAML blocks remain readable as collapsible data:
+
+```json
+{
+  "portal": "static",
+  "search": "pagefind",
+  "themes": ["light", "dark"]
+}
+```
+
+```yaml
+contentPath: ./docs
+publish: github-pages
+sourceOfTruth: consumer-repository
+```
+
+CSV becomes a table when the content is tabular:
+
+```csv
+capability,status
+custom-css,available
+blocklist,available
+pagefind,available
+```
+
+### Links and navigation
+
+Regular Markdown links are best for stable routes, such as [site validation](../guides/validate-your-site/). Wiki links are useful when the source repository refers to files by name, such as `[[README]]`. Missing wiki-link targets fail the build instead of producing broken navigation.
+
+## Consumer customization
+
+The consumer changes identity and presentation in `.upcontent/`, without editing the portal renderer:
+
+```text
+.upcontent/
+├── config.json
+├── favicon.svg
+├── logo.svg
+└── theme.css
+```
+
+The configuration controls:
+
+- Site title, description, URL, logo, and favicon
+- Repository links and local custom CSS
+- Social links, table of contents, pagination, last-updated metadata, and code styling
+- Sidebar roots, labels, and content blocklists
+- The frontmatter field used as a page title
+
+Example identity configuration:
+
+```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"]
+  }
+}
+```
+
+The [configuration reference](../customization/config-json/) explains every supported field and its fallback behavior.
+
+### Palette variations
+
+The same Starlight surface can carry different consumer identities through tokens and custom CSS:
+
+<PaletteShowcase />
+
+These are examples for a consumer repository, not a runtime theme picker that every published portal needs to expose.
+
+## Content boundaries
+
+The build excludes protected internal paths and consumer blocklists before parsing. This keeps excluded files out of both the content collection and the sidebar.
+
+```json
+{
+  "navigation": {
+    "blocklist": {
+      "exact": ["notes.md"],
+      "prefixes": ["drafts/", "internal/"]
+    }
+  }
+}
+```
+
+Broken wiki links and traversal attempts fail with the source file and invalid reference. The same pipeline also works when `CONTENT_PATH` points to a separate consumer repository.
+
+## Validation and publishing
+
+The repeatable local contract is:
+
+```sh
+pnpm test
+pnpm check
+make build CONTENT_PATH=.
+make check-external
+```
+
+The reference CI workflow validates the site and an external consumer fixture. The deployment workflow publishes `dist/` to a static host such as GitHub Pages.
+
+## Explore the product
+
+- [Your first build](../getting-started/first-build/)
+- [Set up a consumer repository](../getting-started/consumer-repository/)
+- [Authoring content](../guides/authoring-content/)
+- [Validate your site](../guides/validate-your-site/)
+- [Deployment](../deployment/)

package/astro.config.mjs

@@ -0,0 +1,125 @@
+import { fileURLToPath } from 'node:url'
+import { cpSync, existsSync, mkdirSync, statSync } from 'node:fs'
+import { basename, resolve, sep } from 'node:path'
+import { unified } from '@astrojs/markdown-remark'
+import starlight from '@astrojs/starlight'
+import { defineConfig } from 'astro/config'
+import { visit } from 'unist-util-visit'
+import { rehypeCallouts } from './src/lib/rehype-callouts.ts'
+import { remarkStripDuplicateTitle } from './src/lib/remark-strip-duplicate-title.ts'
+import { remarkStructuredDataPreview } from './src/lib/remark-structured-data-preview.ts'
+import { remarkWikiLinks } from './src/lib/remark-wiki-links.ts'
+import { getPortalConfig } from './src/lib/portal-config.ts'
+import { buildSidebar } from './src/lib/sidebar.ts'
+import { PRODUCT_NAME, PRODUCT_TAGLINE } from './src/lib/product-identity.ts'
+
+const docsRoot = fileURLToPath(new URL('./src/content/docs', import.meta.url))
+const portalConfig = getPortalConfig()
+
+function resolvePortalAsset(assetPath) {
+  if (!assetPath || assetPath.startsWith('http')) return assetPath
+  if (assetPath.startsWith('/')) return assetPath
+
+  const source = resolve(docsRoot, assetPath)
+  if (!source.startsWith(`${resolve(docsRoot)}${sep}`) || !existsSync(source) || !statSync(source).isFile()) {
+    console.warn(`[${PRODUCT_NAME}] Portal asset not found: ${source}`)
+    return undefined
+  }
+
+  const targetDir = resolve(process.cwd(), 'public/upcontent-assets')
+  mkdirSync(targetDir, { recursive: true })
+  const targetName = basename(source)
+  cpSync(source, resolve(targetDir, targetName))
+  return `/upcontent-assets/${targetName}`
+}
+
+function resolvePortalLogo(logo) {
+  if (!logo) return undefined
+  if (logo.src.startsWith('http') || logo.src.startsWith('/')) return logo
+  const source = resolve(docsRoot, logo.src)
+  if (!source.startsWith(`${resolve(docsRoot)}${sep}`) || !existsSync(source) || !statSync(source).isFile()) {
+    console.warn(`[${PRODUCT_NAME}] Portal logo not found: ${source}`)
+    return undefined
+  }
+  const targetDir = resolve(process.cwd(), 'src/assets')
+  mkdirSync(targetDir, { recursive: true })
+  const target = resolve(targetDir, 'consumer-logo.svg')
+  cpSync(source, target)
+  return { ...logo, src: './src/assets/consumer-logo.svg' }
+}
+
+const consumerCss = (portalConfig.theme?.customCss ?? [])
+  .map(cssPath => resolve(docsRoot, cssPath))
+  .filter(cssPath => {
+    if (existsSync(cssPath)) return true
+    console.warn(`[${PRODUCT_NAME}] Custom CSS file not found: ${cssPath}`)
+    return false
+  })
+
+const customCss = ['./src/styles/callouts.css', './src/styles/structured-data-preview.css', ...consumerCss]
+const starlightOptions = portalConfig.starlight ?? {}
+
+// Remark plugin: converts ```mermaid blocks to <div class="mermaid"> BEFORE Shiki runs
+function remarkMermaid() {
+  return (tree) => {
+    visit(tree, 'code', (node, index, parent) => {
+      if (node.lang !== 'mermaid') return
+      // <br/> inside a div becomes a DOM element before Mermaid parses the text, breaking the parser
+      const safe = node.value.replace(/<br\s*\/?>/gi, ' ')
+      parent.children.splice(index, 1, {
+        type: 'html',
+        value: `<div class="mermaid">${safe}</div>`,
+      })
+      return index + 1
+    })
+  }
+}
+
+// Rehype plugin: strip .md suffix from internal hrefs so links resolve correctly
+function rehypeStripMdLinks() {
+  return (tree) => {
+    visit(tree, 'element', (node) => {
+      if (node.tagName !== 'a') return
+      const href = node.properties?.href
+      if (typeof href !== 'string') return
+      if (href.startsWith('http://') || href.startsWith('https://') || href.startsWith('#')) return
+      if (href.endsWith('.md')) node.properties.href = href.slice(0, -3)
+    })
+  }
+}
+
+export default defineConfig({
+  output: 'static',
+  site: process.env.SITE_URL || portalConfig.site?.url || undefined,
+  base: process.env.BASE_PATH || undefined,
+  integrations: [
+    starlight({
+      title: portalConfig.site?.title ?? PRODUCT_NAME,
+      description: portalConfig.site?.description ?? PRODUCT_TAGLINE,
+      logo: resolvePortalLogo(portalConfig.site?.logo),
+      favicon: resolvePortalAsset(portalConfig.site?.favicon),
+      components: {
+        Head: './src/overrides/Head.astro',
+        Footer: './src/overrides/Footer.astro',
+      },
+      customCss,
+      social: starlightOptions.social,
+      tableOfContents: starlightOptions.tableOfContents,
+      lastUpdated: starlightOptions.lastUpdated,
+      pagination: starlightOptions.pagination,
+      expressiveCode: starlightOptions.expressiveCode,
+      sidebar: buildSidebar(docsRoot),
+    }),
+  ],
+  markdown: {
+    processor: unified({
+      remarkPlugins: [
+        remarkStripDuplicateTitle,
+        [remarkWikiLinks, { contentRoot: docsRoot, failOnBrokenLinks: true }],
+        remarkMermaid,
+        remarkStructuredDataPreview,
+      ],
+      rehypePlugins: [rehypeCallouts, rehypeStripMdLinks],
+    }),
+  },
+})

package/customization/config-json.md

@@ -0,0 +1,92 @@
+---
+title: JSON configuration reference
+description: Complete reference for the consumer-owned .upcontent/config.json file.
+sidebar:
+  order: 6
+---
+
+The `.upcontent/config.json` file is optional. An omitted field uses the portal or Starlight default.
+
+## Start with the minimum
+
+You only need a title and repository link to get started. Add a logo and custom CSS when you are ready to make the portal yours:
+
+```json
+{
+  "site": {
+    "title": "Engineering Docs",
+    "description": "Documentation for the engineering team."
+  },
+  "repo": {
+    "url": "https://github.com/acme/engineering-docs"
+  }
+}
+```
+
+Relative asset paths resolve from the consumer repository. Absolute URLs are also supported for externally hosted assets.
+
+## Complete example
+
+The optional fields below cover navigation, Starlight presentation, and content conventions. You can add them one group at a time.
+
+<details>
+<summary>Show the complete configuration</summary>
+
+```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"
+  },
+  "theme": {
+    "customCss": [".upcontent/theme.css"]
+  },
+  "starlight": {
+    "social": [
+      { "icon": "github", "label": "GitHub", "href": "https://github.com/acme/engineering-docs" }
+    ],
+    "tableOfContents": { "minHeadingLevel": 2, "maxHeadingLevel": 3 },
+    "lastUpdated": true,
+    "pagination": true,
+    "expressiveCode": {
+      "styleOverrides": { "borderRadius": "0.6rem" }
+    }
+  },
+  "navigation": {
+    "roots": ["README.md", "guides"],
+    "labelOverrides": { "api": "API reference" },
+    "blocklist": {
+      "exact": ["notes.md"],
+      "prefixes": ["drafts/"]
+    }
+  },
+  "content": {
+    "titleField": "title"
+  }
+}
+```
+
+</details>
+
+## Field groups
+
+| Group | Controls |
+| --- | --- |
+| `site` | Name, description, URL, logo, and favicon. |
+| `repo` | Source repository links. |
+| `theme` | Consumer-owned local CSS. |
+| `starlight` | Safe layout, social, table of contents, pagination, and code options. |
+| `navigation` | Sidebar roots, labels, and blocklists. |
+| `content` | Frontmatter title field selection. |
+
+Invalid curated values are ignored or fall back safely. Heading levels must be integers from 1 through 6, and the minimum cannot exceed the maximum.

package/customization/content.md

@@ -0,0 +1,48 @@
+---
+title: Content behavior
+description: Configure page titles, metadata, and the Markdown features available to authors.
+sidebar:
+  order: 5
+---
+
+Upcontent accepts Markdown and MDX files from the consumer repository. Starlight provides the page layout and frontmatter schema; Upcontent adds title fallback, wiki links, callouts, Mermaid, and structured previews.
+
+## Choose a title field
+
+If an existing repository uses a field such as `heading` instead of `title`, configure it once:
+
+```json
+{
+  "content": {
+    "titleField": "heading"
+  }
+}
+```
+
+When the configured field is missing, the portal falls back to the filename. A file named `first-build.md` becomes `First Build`.
+
+## Page metadata
+
+Use frontmatter at the top of a page:
+
+```md
+---
+heading: Configure a consumer repository
+sidebar:
+  order: 2
+---
+```
+
+Use `##` for body sections because the page title is rendered as the top-level heading.
+
+## Supported content features
+
+- Obsidian-style callouts for notes, tips, cautions, and dangers
+- Mermaid diagrams with theme-aware rendering and interaction controls
+- JSON and YAML data previews
+- CSV tables
+- `[[wiki links]]` with build-time target validation
+- Syntax-highlighted code blocks
+- Standard Markdown links, tables, lists, and images
+
+See [Authoring content](../guides/authoring-content/) for writing rules and the [capability showcase](../showcase/) for rendered examples.

package/customization/environment.md

@@ -0,0 +1,43 @@
+---
+title: Environment variables
+description: Configure repository links and hosting paths at build time.
+sidebar:
+  order: 7
+---
+
+The portal is static, but a few values belong to the build environment rather than consumer content.
+
+## Supported variables
+
+| Variable | Purpose | Example |
+| --- | --- | --- |
+| `CONTENT_PATH` | Filesystem path passed to `make dev` or `make build`. | `./` |
+| `REPO_URL` | Overrides the configured source repository URL for generated GitHub links. | `https://github.com/acme/docs` |
+| `BASE_PATH` | URL prefix for a project site hosted below the domain root. | `/engineering-docs` |
+| `SITE_URL` | Canonical site origin used by Astro integrations such as the sitemap. | `https://docs.example.com` |
+
+## Local development
+
+Pass the content path to Make:
+
+```sh
+make dev CONTENT_PATH=.
+```
+
+`CONTENT_PATH` is a Make variable, not a value read from `.upcontent/config.json`.
+
+## Static hosting
+
+For GitHub Pages project sites, set a base path and site URL in the deployment workflow:
+
+```yaml
+env:
+  BASE_PATH: /engineering-docs
+  SITE_URL: https://acme.github.io/engineering-docs
+```
+
+For a custom domain or a host serving the site at `/`, leave `BASE_PATH` empty and set `SITE_URL` to the canonical origin.
+
+## Precedence
+
+`REPO_URL` takes precedence over `repo.url` for generated source links. `BASE_PATH` and `SITE_URL` are build inputs; they do not change the consumer configuration file.

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.