Skip to content

CLAUDE.md

Latest commit

 

History

History
80 lines (62 loc) · 4.44 KB

CLAUDE.md

File metadata and controls

80 lines (62 loc) · 4.44 KB
Raw

doc/ — Quarto documentation site

Source for the public ggsql documentation at https://ggsql.org. This directory is the authoritative reference for ggsql syntax and semantics. Other CLAUDE.md files in the repo link here rather than restate.

If you are about to document a clause, layer type, scale, or aesthetic anywhere else: stop and put it here instead.

Layout

doc/
├── _quarto.yml             Quarto project config (navbar, sidebar, theme, llms-txt)
├── _brand.yml, styles.scss, ggsql.xml   Branding + the ggsql syntax-highlight definition
├── index.qmd               Landing page
├── faq.qmd
├── get_started/
│   ├── installation.qmd    Platform-specific install + CLI quick reference
│   ├── first_plot.qmd      Tutorial: first visualization
│   ├── grammar.qmd         Grammar of Graphics conceptual foundation
│   ├── anatomy.qmd         Anatomy of a ggsql query
│   ├── tooling/            VS Code / Positron / Jupyter / Python / R / CLI / Wasm
│   └── the_rest.qmd        Advanced features
├── syntax/
│   ├── index.qmd
│   ├── clause/             draw, facet, label, place, project, scale, visualise
│   ├── layer/
│   │   ├── type/           one .qmd per layer type (point, line, bar, …)
│   │   └── position/       identity, stack, dodge, jitter
│   ├── scale/
│   │   ├── type/           binned, continuous, discrete, identity, ordinal
│   │   └── aesthetic/      position, color, opacity, size, linewidth, shape, linetype, faceting
│   └── coord/              cartesian, polar
├── gallery/
│   ├── index.qmd
│   └── examples/           Runnable example queries
├── assets/, vendor/        Static resources
├── data/CSVs               Sample datasets used by examples (data.csv, sales.csv, …)
└── wasm/                   Built playground (copied from /ggsql-wasm/demo/dist by build-wasm.sh)

Generated artefacts not to edit by hand:

  • _site/ — Quarto build output. Not committed (see .gitignore).
  • *.quarto_ipynb* — Quarto's intermediate notebook files for .qmd pages with executable cells. Regenerated on build.
  • wasm/ — produced by /ggsql-wasm/build-wasm.sh.

Authoring conventions

  • Pages are Quarto markdown (.qmd) — markdown plus YAML front-matter.
  • Code blocks tagged ```ggsql use the syntax definition in ggsql.xml (referenced from _quarto.yml under syntax-definitions). Use that fence for runnable / illustrative ggsql snippets.
  • Each clause page under syntax/clause/ follows the same shape: short narrative, a "Clause syntax" code block listing all subclauses, then sections per subclause with examples. Mirror that shape when adding pages.
  • Examples that need data reference the CSV files at the top of doc/ (e.g. data.csv, sales.csv, metrics.csv, timeseries.csv).
  • The site has llms-txt: true in _quarto.yml, so an llms.txt is generated for AI tooling — keep page titles and descriptions clean.

Site structure (from _quarto.yml)

  • Navbar: Get started · Syntax (drop-down per clause) · Gallery · FAQ · News · Playground · Python · R.
  • Syntax sidebar: clauses → layers (type + position) → scales (type + aesthetic) → coordinate systems. New .qmd files in those folders are picked up automatically via auto: glob entries.
  • Get-started sidebar: hand-ordered list (installation → first_plot → grammar → anatomy → tooling → the_rest).

Build & preview

cd doc
quarto preview     # local server with hot reload
quarto render      # full site build → _site/

The site is published from the gh-pages branch (see _quarto.yml's repo-branch). Quarto extensions live in _extensions/.

What goes here vs. CLAUDE.md

  • Here: anything a ggsql user might want to read — clause syntax, layer types, scales, aesthetics, examples, CLI usage, installation.
  • In CLAUDE.md files: implementation details for contributors — module layouts, build pipelines, where to add a new geom, internal types.

If you find clause/layer/scale syntax described in any CLAUDE.md file, that is a duplication bug — move it here and link from there.

See also