# `.help/` — source for the TiXL docs site

This directory is the source of truth for TiXL's user-facing documentation. It publishes to `help.tixl.app` via a MkDocs Material build on Vercel.

- **Public landing page:** [`docs/index.md`](docs/index.md)
- **Writing style and conventions:** [`docs/STYLE.md`](docs/STYLE.md) — read before opening a docs PR.
- **Plan and open work:** [`../.agentic/Plans/Plan_UpdateHelp.md`](../.agentic/Plans/Plan_UpdateHelp.md)
- **Source material (scripts, release notes, etc.):** [`.src/`](.src/) — raw tutorial scripts and transcripts used as draft material. Not published.

Developer-focused pages (building TiXL from source, coding conventions, CI, release process) stay on the [GitHub wiki](https://github.com/tixl3d/tixl/wiki). Don't mix the two — user-facing here, contributor-facing there.

## Layout

```
.help/
├── README.md                 # this file — contributor orientation, not published
├── mkdocs.yml                # site config (Material theme, awesome-pages plugin)
├── requirements-docs.txt     # Python deps for building the site
├── docs/                     # ← the actual documentation (mkdocs docs_dir)
│   ├── index.md              # site landing page
│   ├── STYLE.md              # writing conventions
│   ├── .pages                # top-level nav order (awesome-pages plugin)
│   ├── getting-started/      # what is TiXL, install pointers, concepts, tutorials
│   ├── install/              # installation and dev environment
│   ├── using/                # day-to-day reference — UI, graphs, IO, export, live
│   ├── advanced/             # custom shaders, C# ops, fonts
│   ├── contributing/         # docs + dev onramps
│   └── operators/            # auto-generated from SymbolUi (do not hand-edit)
├── site/                     # build output — gitignored, re-generated by `mkdocs build`
└── .src/                     # raw source material for future pages — not published
```

Each section folder has its own `README.md` that lists the pages present *and* the pages still to write. When a topic is missing, don't create an empty placeholder — add a one-liner under "Still to write" and flesh it out when you have something concrete to say.

## Building locally

```bash
pip install -r .help/requirements-docs.txt
mkdocs serve -f .help/mkdocs.yml
```

Preview on `http://127.0.0.1:8000/`. The site auto-reloads on changes under `docs/`.

## Section READMEs

- [Getting started](docs/getting-started/README.md)
- [Install](docs/install/README.md)
- [Using TiXL](docs/using/README.md)
- [Advanced](docs/advanced/README.md)
- [Contributing](docs/contributing/README.md)