# Docs

Please follow LiveStore's [guiding principles](/sustainable-open-source/contributing/info#guiding-principles) when writing docs.

## Writing style

This project broadly tries to follow the [Prisma docs style guide](https://www.prisma.io/docs/about/style-guide/writing-style).

## Use regular sentence casing for titles of navigation item, pages and sections

All titles for navigation items, pages and sections are using regular sentence casing. This means that only the first word and proper nouns (e.g. "Cloudflare Workers" or "Cloudflare Durable Objects") are capitalized.

### Example 1

Good:

```md
## This is the title of this section
```

Bad:

```md
## This is the Title of this Section
```

### Example 2

Good:

```md
## This pages is about Cloudflare Workers
```

Bad:

```md
## This pages is about cloudflare workers
```

## Create proper frontmatter for every page

Frontmatter is YAML metadata at the start of MD/MDX files (between `---` markers) that controls page rendering, navigation, and SEO.

### Required fields

- **`title`**: Page title used for the browser tab, search results, and page heading. Always required.
- **`description`**: Brief summary (150-160 characters) used for search snippets and social previews. Highly recommended for SEO.

### Optional fields

- **`sidebar`**: Controls sidebar navigation
  - `label`: Custom sidebar label (defaults to `title`)
  - `order`: Numeric sort order (lower numbers appear first)

### SEO impact

The `title` and `description` fields directly impact SEO:

- `title` becomes the `<title>` tag and search result headline
- `description` becomes the `<meta name="description">` tag and search snippet
- Both are used for Open Graph and Twitter Card previews
- OG images are auto-generated at `/og/{slug}.png` using these fields

### Examples

Minimal (title only):

```yaml
---
title: Getting started with LiveStore + React
---
```

With description and sidebar:

```yaml
---
title: Getting started with LiveStore + React
description: How to use LiveStore with React on the web.
sidebar:
  label: React web
  order: 1
---
```

## Snippets

For snippet guidelines, see: `/contributor-docs/docs/snippets.md`

## Deploying the docs

- Run `direnv exec . mono docs deploy` to deploy the already-built documentation to the dev Netlify site. On `main`, this updates the dev domain (`https://dev.docs.livestore.dev`); on pull requests and feature branches, it uses a branch alias on the dev site.
- Passing `--prod` targets the production domain (`https://docs.livestore.dev`) and is only allowed for stable LiveStore release versions.
- Use `--site=<slug>` if you need to override the default Netlify site name.
- Use `--plan` to print the resolved deploy target without building or deploying. This is the safest way to verify whether a CI event would update the dev site, create PR aliases, or target the production site before running a live deploy.
- Add `--purge-cdn` when you need to invalidate Netlify's CDN cache after deploying; this ensures new edge handlers or content-negotiation changes take effect immediately.
- CI automatically builds and deploys the docs: normal `main` pushes update `https://dev.docs.livestore.dev`, pull requests publish aliases on the dev site, and the release workflow updates `https://docs.livestore.dev` only after publishing a stable release.