xberg-brand-and-docs

name	xberg-brand-and-docs
description	Canonical xberg.io brand, product catalog, docs-site (Astro Starlight + @xberg-io/docs-theme), alef badge, docs task commands, prose style, Google Analytics IDs, brand assets, and README-template policy. Load when writing READMEs or docs, editing docs-site config, adding the ecosystem block or alef badge, or touching brand/analytics wiring.

Xberg Brand and Docs

Company: Kreuzberg, Inc. Landing: xberg.io Open-source docs domain pattern: docs.<repo>.xberg.io (core extraction lib uses bare docs.xberg.io) Commercial docs domain: enterprise.xberg.io

Authoritative product list (use this exact ordering and wording in every README ecosystem block):

• Xberg — the open-source content-intelligence engine: text, tables, and metadata from 101 formats (115 file extensions), with OCR, transcription, and code intelligence. MIT.
• Xberg Pro — a complete self-hosted content-intelligence backend in a single container. Commercial.
• Xberg Enterprise — the distributed, governed content-intelligence platform, scaled on Kubernetes with team governance and support. Commercial.
• crawlberg — web crawling and scraping with HTML→Markdown and headless-Chrome fallback.
• html-to-markdown — fast, lossless HTML→Markdown engine.
• liter-llm — universal LLM API client with native bindings for 14 languages and 165 providers.
• tree-sitter-language-pack — tree-sitter grammars and code-intelligence primitives.
• alef — the polyglot binding generator that produces every per-language binding across the 5 polyglot repos.

Alef badge (polyglot repos only — xberg, h2m, tslp, lllm, crawlberg):

[![Built with alef](https://img.shields.io/badge/built%20with-alef%20%D7%90-007ec6)](https://github.com/xberg-io/alef)

The %D7%90 URL-encodes the Hebrew letter א (Aleph) — the canonical alef brand mark. Place in the badge row at the top of each polyglot repo's root README, and inside the alef-generated badge partial so every per-package README inherits it.

Ecosystem-block links MUST use the GitHub repo URLs (github.com/xberg-io/<repo>), not the docs.<repo>.xberg.io subdomains — GitHub links push traffic to the source repos, encouraging stars.

Docs sites are Astro Starlight projects under docs-site/, consuming the shared @xberg-io/docs-theme npm package (its own repo, xberg-io/docs-theme). The theme bakes in the brand — navy/cyan/blue/purple palette, Exo 2, CDN logo (SiteTitle override), and favicon/OG/Google Analytics head tags — through xbergStarlightConfig(); do NOT re-add per-repo brand CSS or GA.

• docs-site/astro.config.mjs: starlight(xbergStarlightConfig({ title, githubUrl, sidebar, plugins: [starlightLlmsTxt()] })). Import starlight and Starlight plugins in the consuming config (the theme is import-free).
• Content lives in docs-site/src/content/docs/ (.mdx for pages using tabs/components, .md otherwise); code snippets in docs-site/src/snippets/; the alef-generated reference goes to docs-site/src/content/docs/reference/ (always .md).
• Sidebar (in astro.config.mjs): Home → Get Started → Guides → Concepts → Reference → More
• index.mdx: splash — hero (light/dark image variants) → "Why X" CardGrid → Language Support table → Quick Example tabs → "Part of Xberg.io" ecosystem LinkCards → "Explore the Docs" cards → Getting Help
• llms.txt is generated by the starlight-llms-txt plugin (added per-site under plugins).

Every repo's root Taskfile exposes the same docs commands via .task/tools/docs.yml:

• task docs:build — build the site (pnpm --dir docs-site build)
• task docs:serve — local dev server with live reload (pnpm --dir docs-site dev)
• task docs:lint:links — lychee link check
• task docs:lint:prose — textlint prose lint
• task docs:snippets:validate — validate docs-site/src/snippets/ via alef snippets

CI builds and deploys to GitHub Pages via the shared reusable workflow xberg-io/actions/.github/workflows/reusable-docs-deploy.yml@v1.

Prose style: terse, second-person imperative. No marketing adjectives. No emoji headers. Lead with structural facts ("Eight extraction functions are available…") rather than "This section will walk you through…". Use admonitions only for genuine tip/warning/info callouts.

Google Analytics IDs (canonical, all 6 docs sites):

• Web property: G-8G4NQW55PF
• Google Ads conversion: AW-17853694443

Both IDs are injected by @xberg-io/docs-theme (the head tags in xbergStarlightConfig). Do not introduce per-repo GA properties without an explicit business reason.

Brand assets: logos, favicons, and the OG card are served from xberg-io/assets via jsDelivr (@v1) and wired through @xberg-io/docs-theme. Sites do not vendor their own brand-asset copies. The hero uses light/dark variants (hero-logo.svg / hero-logo-light.svg).

README-template policy: where a repo's root README.md is generator-driven, edit the template only — never hand-edit the generated README.md. The generated file is checked in but is downstream output.

• xberg, xberg-enterprise: hand-written root READMEs (direct edits OK)
• html-to-markdown, tree-sitter-language-pack, liter-llm, crawlberg: alef-generated from readme_templates/ — edit the template, run alef readme