Style principles, page structure, and writing rules for all CedarDB documentation.

Readers are technical: developers, DBAs, and data engineers comfortable with SQL and database concepts. Assume SQL familiarity. Do not explain foundational database concepts (what a table is, what a transaction does). Do explain what CedarDB does, how each feature works, and where behavior differs from PostgreSQL.

Precise and factual. Think: a senior engineer explaining something clearly. Confident, concise, helpful. Never condescending. Neutral in reference docs. Strengths may be highlighted in best-practices content.

• Address the reader as "you" -- most natural in tutorials, used sparingly in reference descriptions.
• Active voice by default. "CedarDB returns the result." Not "The result is returned by CedarDB."
• Never use "we" to describe product behavior. Use "CedarDB" or "the database."

• American English. "analyze" not "analyse", "behavior" not "behaviour."
• Oxford comma. "tables, views, and indexes."
• SQL keywords in uppercase in both prose and code blocks: SELECT, ALTER TABLE.
• Backticks for inline technical names: statement_timeout, psql, pg_catalog.
• "CedarDB" (not "Cedar DB", "cedar"). "PostgreSQL" (not "Postgres", "PG") in prose. Technical names like pg_catalog or psql are fine as-is.
• Page titles: title case. Subsection headings: sentence case — except on object reference pages (tables, roles, indexes, …) where top-level subsections are named after the SQL statement they cover: ## CREATE TABLE, ## ALTER TABLE, ## DROP TABLE. Use the exact SQL keyword in uppercase.
• Sentences: keep them short. One idea per sentence. Under 25 words as a target.

Every SQL reference page follows this structure. Omit a section only if it genuinely does not apply. Do not leave sections empty or include placeholders.

Railroad diagrams are the primary way to communicate syntax. Use the {{</* railroad */>}} shortcode. Only document syntax that CedarDB actually supports — omit clauses that are not yet implemented rather than greying them out. Follow the diagram with a plain-text syntax block as a fallback for readers who prefer text, and as the source of truth for the options table below.

Same opening structure (summary, quick example) but replace the formal syntax section with step-by-step instructions. Each step must be independently executable -- the reader should be able to copy-paste the code block for that step without needing to have read previous steps.

Start with the simplest correct path (happy path first). Introduce complexity and edge cases later, clearly labeled.

Use tables with a traffic-light status column using inline emoji:

• Every entry with a reference page must link to it.
• Full means core PostgreSQL functionality works. Minor missing sub-features (edge-case options, rarely-used clauses) do not prevent a Full rating. Document the gaps in the reference page's "PostgreSQL Differences" section, not here.
• Partial means meaningful, commonly-used functionality is missing. Link to the reference page only — do not list limitations inline in the matrix.
• No means the feature is not supported at all.
• All Partial and No entries must be verified by testing. Do not guess.
• Never link to PostgreSQL docs from compatibility entries.

Every directory that groups related pages must have an _index.md. It serves as the landing page for that section in the navigation and is the first thing a reader sees when arriving at a section from a search result or a cross-link.

Structure:

Keep the overview to two or three sentences. It should answer "what will I find here?" and orient the reader before they click into a specific page. Do not repeat the section title verbatim as the first sentence.

The member list must stay in sync with the actual pages in the directory. When a page is added or removed, update the _index.md in the same PR.

Example:

CedarDB supports the standard SQL data types, with extensions for analytical
workloads. Each page covers the type's storage format, valid ranges, casting
rules, and any differences from PostgreSQL.

- [Integer types](integer) — `smallint`, `integer`, `bigint`, and serial variants
- [Numeric](numeric) — arbitrary-precision `numeric` and `decimal`
- [Text](text) — `text`, `varchar`, and `char`
- [JSON](json) — `json` and `jsonb` with operator and function reference

Separate from reference docs. Cover where CedarDB excels, known limitations with recommended workarounds, and optimization guidelines. May highlight strengths. Include benchmarks or explanations where relevant.

1. Self-contained. Include the CREATE TABLE or equivalent setup needed to run the example. Do not assume state from elsewhere in the docs.
2. Copy-pasteable. The code block runs without modification in a CedarDB psql session.
3. Show expected output when the result is non-obvious or demonstrates specific behavior. Use the psql tabular format in a separate code block or as comments.
4. No cross-page running examples. Each page uses its own schema. Do not build on tables defined in other pages.
5. Consistent naming theme. Use plant and tree themed names where they fit naturally: trees, forests, plants, species, growth_rate, height, bloom_date. Fall back to other realistic domain names (orders, customers, amount) when a botanical theme would feel forced for the concept being demonstrated. Never use meaningless names like t, a, b, foo.
6. One concept per example. Do not combine unrelated features.
7. Keep it short. Under 10 lines preferred. 15 lines maximum for complex features (transactions with savepoints, multistep migrations).

-- Create the table
CREATE TABLE trees (
    id          integer PRIMARY KEY,
    species     text    NOT NULL,
    height_m    numeric NOT NULL,
    planted     date    DEFAULT current_date
);

-- Insert a row
INSERT INTO trees VALUES (1, 'Oak', 12.4, '2015-03-10');

-- Verify
SELECT * FROM trees;

 id | species | height_m |  planted
----+---------+----------+------------
  1 | Oak     |     12.4 | 2015-03-10

CedarDB is PostgreSQL-compatible. Many readers arrive with PostgreSQL knowledge. Leverage that, but never send readers away to read PostgreSQL docs.

No external PostgreSQL links. Never link to postgresql.org. If the reader needs more context, document it in CedarDB docs. Linking externally signals immaturity and causes drop-off.

When CedarDB extends PostgreSQL, call it out positively: "In addition to standard PostgreSQL behavior, CedarDB also supports ..." Do not frame additions as edge cases.

If a reference page has any behavioral difference from PostgreSQL, include a "PostgreSQL Differences" section. Use a bulleted list. If there are no differences, omit the section entirely.

## PostgreSQL Differences

- `ON CONFLICT DO UPDATE` is supported; `ON CONFLICT DO NOTHING` is not yet available.
- The `RETURNING` clause supports all column expressions.

Lead with what CedarDB can do. Limitations and PostgreSQL differences belong in a clearly labeled section near the bottom of the page, not in a warning at the top.

The CedarDB docs must function as a complete reference. Readers should never need to leave the site to understand how to use a feature.

• Do not link to external documentation to explain a concept. Document it here.
• Internal cross-links are encouraged. Link to related CedarDB pages freely.
• If a concept needs context (e.g., what snapshot isolation means), explain it briefly in the description section rather than linking elsewhere.

A complete set of documentation, even for simple features, signals project maturity. Do not skip documenting something because it seems basic or obvious.

Enterprise evaluators check for completeness, not sophistication. Document the boring stuff.

• Features that are not yet implemented. The roadmap covers planned work.
• Internal implementation details unless they affect user-visible behavior.
• Workarounds for missing features. If a feature is missing, say so and stop.

CedarDB does not maintain versioned documentation. All documentation describes the current stable release. Versioned docs encourage users to stay on old versions and create back-porting pressure.

When features change between versions, update the existing page. Release notes in releases.md track what changed per version.

Documentation must be written and approved before the corresponding code change is merged. Submit a documentation PR alongside the code PR. The documentation PR must be approved before the code PR can be merged.

If you discover a mismatch between docs and behavior during routine development, fix it immediately in the same PR. Do not file "fix docs later" tickets.

• SQL code blocks use the sql language tag.
• Shell commands use bash or no tag. Prefix with $ only when mixing commands with output.
• Syntax definitions use no language tag. Use <angle brackets> for placeholders and [square brackets] for optional parts.

• Use Hugo admonitions sparingly. Two types: info (supplementary context) and warning (behavior that might surprise the reader or cause data loss).
• Limit to one admonition per page section. If you need more, revise the prose to incorporate the information directly.
• Use Markdown tables for structured information. Keep cells simple. If a cell needs more than one sentence, use prose instead.