# Byline CMS

> A developer-friendly, open-source headless CMS — built with versioning, editorial workflow, and content translation.

## Documentation

- [Search & Document Extraction](https://bylinecms.app/docs/search-extraction-strategy.md): Forward-looking research for attachment extraction and retrieval: provider boundaries, persistence, indexing, chunking, and phased delivery.
- [Getting Started](https://bylinecms.app/docs/getting-started.md): Two ways to get started with Byline: add it to an existing TanStack Start app with the CLI, or clone this repo and run the example application in dev mode.
- [CLI](https://bylinecms.app/docs/getting-started/getting-started-cli.md): Add Byline to an existing TanStack Start application with 'byline init', provision and seed a hand-wired application with 'byline setup', and check an installation with 'byline doctor'.
- [Development environment and example application](https://bylinecms.app/docs/getting-started/getting-started-development-environment.md): Clone the Byline CMS repo, provision PostgreSQL, seed the database, and run the example application (apps/webapp) in dev mode.
- [Configuration](https://bylinecms.app/docs/getting-started/configuration.md): A tour of the application-owned Byline files: which configuration belongs on the server, in the admin module graph, in isomorphic schemas, and behind the public client-safe facade.
- [Upgrading from 3.21 to 4.x](https://bylinecms.app/docs/getting-started/upgrading-to-v4.md): Application migration guide for Byline 4.x: package alignment, route configuration, server-only lifecycle hooks, package-import surface for clients and generated types, request contexts, and release validation.
- [Upgrading from 4.11 to 4.12](https://bylinecms.app/docs/getting-started/upgrading-to-v4-12.md): Application migration guide for Byline 4.12: admin configuration naming, admin locale naming, host-owned site URLs, removed compatibility APIs, and coordinated package validation.
- [Why Byline](https://bylinecms.app/docs/why-byline.md): The thinking behind Byline: why it exists, the problems it sets out to solve, and what it means to build a content platform for an era in which both people and machines read your content.
- [Mission & Vision](https://bylinecms.app/docs/why-byline/mission.md): Why Byline exists: an AI-first, structurally sound headless CMS that takes versioning, workflow, translation, and editorial provenance seriously by default.
- [Content Management in the Time of AI](https://bylinecms.app/docs/why-byline/content-in-the-time-of-ai.md): Why structured versioning, workflow, and translation matter more, not less, when AI starts producing content at scale, and what provenance looks like in that world.
- [Byline for Collections](https://bylinecms.app/docs/why-byline/byline-for-collections.md): Why Byline's immutable versioning, default-on workflow, and atomic audit trail make it a strong foundation for digital collections management, and how OAI-PMH, fixity checking, and accession controls would build on that foundation for science, research, cultural, and heritage collections.
- [Key Architectural Decisions](https://bylinecms.app/docs/architecture.md): The load-bearing design decisions behind Byline: universal EAV storage, immutable versioning, the document-level vs version-level split (path, available locales, tree edge), patch-based updates, the schema/admin split, and the authorization model. Each links to its full reference.
- [Core Document Storage](https://bylinecms.app/docs/architecture/core-document-storage.md): How Byline stores documents: typed store tables, field paths, flatten and reconstruct, immutable versioning, the current-version views, and what the model costs you.
- [Core Composition](https://bylinecms.app/docs/architecture/core-composition.md): The seams Byline composes at boot: the database, storage, session, and search adapters, the field-level server slots, the initBylineCore() entry point, and the rules that keep those boundaries stable.
- [Transactions](https://bylinecms.app/docs/architecture/transactions.md): What Byline guarantees to write atomically and what it does not, the transaction capability every database adapter must supply, and the AsyncLocalStorage propagation that makes composed writes possible.
- [Path Grammar](https://bylinecms.app/docs/architecture/path-grammar.md): How Byline identifies fields in stored documents, schemas, patches, forms, and upload configuration: the two path notations, when to use each, and their APIs and limits.
- [Deployment Topologies](https://bylinecms.app/docs/architecture/deployment-topologies.md): The deployment shapes Byline supports: a single integrated host today, and the progressively split admin / API / front-end topologies that a stable HTTP boundary unlocks.
- [Collections](https://bylinecms.app/docs/collections.md): Defining collections in Byline: defineCollection, the workflow system, lifecycle hooks (beforeCreate, beforeRead, afterUpdate…), and the admin presentation split.
- [Fields](https://bylinecms.app/docs/collections/fields.md): Fields in Byline: built-in types, optional, localized, validation, hooks, conditional visibility, cross-field writes, the schema-vs-admin split, and how to build reusable field helpers like publishedOnField.
- [Blocks](https://bylinecms.app/docs/collections/blocks.md): Block architecture: defineBlock, the per-block schema/admin split (defineBlockAdmin), tailoring editors per block, blocks in type generation and storage, inline uploads with upload.location, and the reference blocks.
- [Relationships](https://bylinecms.app/docs/collections/relationships.md): First-class typed relations: the populate pipeline, depth-bounded recursion via ReadContext, two-axis populate DSL, and the unified relation envelope across all states.
- [Document Trees](https://bylinecms.app/docs/collections/document-tree.md): A document-level, single-parent, ordered hierarchy for self-referential collections: enable it with tree: true for a navigable table of contents, hierarchical URLs, breadcrumbs, and prev/next, all without versioning the structure.
- [Document Paths](https://bylinecms.app/docs/collections/document-paths.md): How byline_document_paths keys (document_id, locale) → path, why path lives outside the EAV stores, and how the slugifier resolves uniqueness on create and update.
- [File / Media Uploads](https://bylinecms.app/docs/collections/file-media-uploads.md): The full upload pipeline: field-level validation, storage providers, image variant generation via Sharp, and how the Media collection plus a relation forms a shared library.
- [Rich Text Editor](https://bylinecms.app/docs/collections/richtext.md): Byline's Lexical-based rich text editor: the extension API, built-in nodes (links, inline images, admonitions, layout, code, tables), and the runtime serializer pipeline.
- [Collection Versioning](https://bylinecms.app/docs/collections/collection-versioning.md): Byline records which schema version each document was written against. How the collection fingerprint (schema_hash) decides when a version bumps, the auto-bump-with-pin policy, startup reconciliation, and the boundary: what is recorded today versus what is not yet read by version.
- [Reading & Delivery](https://bylinecms.app/docs/reading-and-delivery.md): How content leaves Byline and reaches its readers through the typed client SDK, server-function transports, markdown and llms.txt exports, future MCP support, and application caching.
- [Client SDK (@byline/client)](https://bylinecms.app/docs/reading-and-delivery/client-sdk.md): The in-process @byline/client SDK above the storage primitives: find, create, update, populate, status-aware reads, plus the read and write hook contracts.
- [Routing & API](https://bylinecms.app/docs/reading-and-delivery/routing-api.md): The current internal-transport phase (TanStack Start server functions per area) and why a stable public HTTP API is deferred until a second client arrives.
- [Transports](https://bylinecms.app/docs/reading-and-delivery/transports.md): The pluggable transport family: a single framework-agnostic operation contract bound to many runtimes (Nitro, Fastify, Hono) plus MCP as a peer transport. The concrete shape of the stable boundary Routing & API defers.
- [Markdown Export](https://bylinecms.app/docs/reading-and-delivery/markdown-export.md): The agent-readable surface: one-way Lexical → markdown serialization, the documentToMarkdown assembler, .md routes per content locale, llms.txt, and the three advertisement channels.
- [MCP Server](https://bylinecms.app/docs/reading-and-delivery/mcp.md): Planned Model Context Protocol support: a peer transport binding the operation layer to MCP tools, resources, and prompts, with draft-by-default writes, service-account authentication, and workflow review.
- [Caching](https://bylinecms.app/docs/reading-and-delivery/caching.md): How Byline applications cache HTML at the CDN edge, how editors bypass that cache for instant preview, and where an optional in-memory data cache fits.
- [Search](https://bylinecms.app/docs/search.md): How Byline provides ranked, multilingual site search through one provider contract, with built-in PostgreSQL and MySQL implementations that reuse the application's existing database.
- [Configure search](https://bylinecms.app/docs/search/configure-search.md): How to register a PostgreSQL or MySQL search provider and declare the collection fields, weights, zones, and rich-text adapter that feed the index.
- [Indexing and reindexing](https://bylinecms.app/docs/search/search-indexing.md): How published document versions enter and leave the search index, how lifecycle hooks reconcile changes, and when to rebuild the disposable projection.
- [Search API](https://bylinecms.app/docs/search/search-api.md): Reference for collection and zone search, matching options, ranked hits, highlighted snippets, hydration, authorization, and current query limits.
- [Search provider contract](https://bylinecms.app/docs/search/search-provider-contract.md): Reference for SearchProvider, SearchDocument, capability declarations, provider responsibilities, and the shared conformance suites.
- [Portable multilingual search analysis](https://bylinecms.app/docs/search/multilingual-search-analysis.md): How Byline normalizes multilingual text, preserves identifiers, plans portable queries, expands language terms, creates highlights, and detects indexes that require rebuilding.
- [PostgreSQL and MySQL search providers](https://bylinecms.app/docs/search/postgres-mysql-search.md): How the built-in SQL providers store, rank, highlight, migrate, and validate the same portable search contract while reusing the application's database.
- [Attachment extraction for search](https://bylinecms.app/docs/search/search-attachment-extraction.md): The planned reusable boundary for extracting text from PDFs and other attachments before published documents enter the search index, and the production experience informing it.
- [Native search engines and backend portability](https://bylinecms.app/docs/search/native-search-engines.md): How one search projection supports both portable SQL analysis and engines with native language analysis, and what stays stable when an installation moves between them.
- [Semantic discovery and institutional standards](https://bylinecms.app/docs/search/semantic-discovery-institutional-standards.md): How Byline's multilingual search foundation, together with capabilities now under development and active research, supports structured, hybrid, relationship-aware, and standards-based discovery for research, library, archive, biodiversity, and cultural-heritage collections.
- [Auth & Security](https://bylinecms.app/docs/auth-and-security.md): How Byline controls who can do what, and how it records what was done: the actor and ability model, two-layer access control with read-side row scoping, and the version and document-level audit trails.
- [Authentication & Authorization](https://bylinecms.app/docs/auth-and-security/authn-authz.md): How actors, abilities, and request context flow through Byline, plus six worked beforeRead recipes for row-level access control on document reads and populate.
- [Auditability](https://bylinecms.app/docs/auth-and-security/audit.md): Present-state reference for the auditability subsystem: the version audit trail (acting user + action), the document-level audit log, the tabbed document-history view, and the system-wide activity area. The internal staff-accountability record behind the public 'who wrote it, who changed it' claim.
- [Internationalization (i18n)](https://bylinecms.app/docs/i18n.md): Byline separates interface translation from content translation, and treats both independently from the language a document is published in. An overview of the three i18n axes (host interface, admin interface, and content locales) and how they stay decoupled.
- [The host i18n system](https://bylinecms.app/docs/i18n/i18n-host.md): How a host application coordinates with Byline's content locales: the routable-vs-advertised distinction, the non-sticky content-locale rule, clean default-locale URLs via an isomorphic rewrite, and the single dependency-free reach into Byline's locale set.
- [Admin interface translations](https://bylinecms.app/docs/i18n/i18n-admin.md): Translating the Byline admin shell with the @byline/i18n package: registering the bundled locales, the useTranslation hook, server-side translation, ICU message formatting, per-user locale preference, and the extension surface for plugins and custom fields.
- [Content locales](https://bylinecms.app/docs/i18n/i18n-content-locales.md): The language a document is published in: per-document locale resolution and fallback (onMissingLocale), the version-level completeness rule, and the editorial availableLocales control that decides which locales a document advertises in hreflang, sitemaps, and 'Also available in…' menus.
- [Administering content locales](https://bylinecms.app/docs/i18n/i18n-administering.md): The administrative task of switching a system's default content locale safely: why the default doubles as a per-document data anchor, the per-document source_locale that makes the switch a non-event, and the bulk re-anchor workflow for moving documents onto a new default.
- [Admin UI](https://bylinecms.app/docs/admin-ui.md): The building blocks of Byline's admin interface: the framework-agnostic UI Kit it is built from, and how the admin/editor configuration is registered into a host application without leaking into its public bundles.
- [UI Kit (@byline/ui)](https://bylinecms.app/docs/admin-ui/uikit.md): The shared @byline/ui component library: primitives, themed surfaces, design tokens, and the Rslib build pipeline used to ship it to admin and downstream consumers.
- [Admin-config registration](https://bylinecms.app/docs/admin-ui/client-config-registration.md): Why the Byline admin config is registered from two points on the _byline route, the root cause that blocks collapsing it to one eager point, and whether an eager single-point registration is even possible given that custom slot components need React context.
- [API Reference](https://bylinecms.app/docs/api-reference.md): Exact configuration, collection, field, and Client SDK contracts, with links to the subsystem references that own search, authentication, uploads, rich text, routing, and storage.
- [Configuration API](https://bylinecms.app/docs/api-reference/configuration-reference.md): Exact BaseConfig, AdminConfig, ServerConfig, BylineCore, route, registration, getter, and server-client contracts.
- [Collections API](https://bylinecms.app/docs/api-reference/collections-reference.md): Exact collection schema, admin presentation, block, workflow, lifecycle hook, layout, column, and preview configuration contracts.
- [Fields API](https://bylinecms.app/docs/api-reference/field-reference.md): All 22 built-in field kinds, common schema properties, type-specific options, inferred value shapes, defaults, validation, hooks, localization, and admin overrides.
- [Client SDK API](https://bylinecms.app/docs/api-reference/client-sdk-reference.md): Exact BylineClient construction, top-level methods, CollectionHandle methods, read and write options, result envelopes, search, history, audit, indexing, and document-tree contracts.
- [Testing](https://bylinecms.app/docs/testing.md): Two suites, two commands: pnpm test (unit, no database) and pnpm test:integration (real PostgreSQL and MySQL). Isolation, safety guards, and how to run a single test file.

## Pages

- [About Byline](https://bylinecms.app/about/about-byline.md): Byline is a content management system built on three pillars — versioning, workflow, and content translation — designed to work together without trade-offs. We're committed to real data ownership and building in the open.
- [Terms of Use](https://bylinecms.app/legal/terms-of-use.md): These are the Terms of Use governing the use of this Service and the agreement that operates between You and the Site Owner. These Terms of Use set out the rights and obligations of all users regarding the use of the Service.
- [Privacy Policy](https://bylinecms.app/legal/privacy-policy.md): Our Privacy Policy describes our policies and procedures on the collection, use and disclosure of your information when you use our website and tells you about your privacy rights and how the law protects you.
- [Cookies](https://bylinecms.app/legal/cookies.md): Infonomic's cookies policy explains what cookies are and how we use them. You should read this policy so you can understand what type of cookies we use, or the information we collect using cookies and how that information is used.