52 lines
3.4 KiB
Markdown
52 lines
3.4 KiB
Markdown
# Agent Instructions
|
|
|
|
This repository is the **user-facing documentation** for Data Controller for SAS®, published at [docs.datacontroller.io](https://docs.datacontroller.io). It is a [MkDocs](https://www.mkdocs.org/) site using the Material theme.
|
|
|
|
## Related repositories
|
|
|
|
Data Controller spans three sibling repositories (usually checked out side by side under the same parent directory):
|
|
|
|
- **`dc`** - the product source (Angular client + SAS backend). The behaviour documented here is implemented there. Deep technical notes live in `dc/.agent/docs/`.
|
|
- **`docs.datacontroller.io`** (this repo) - the user-facing product documentation.
|
|
- **`datacontroller.io`** - the marketing site, blog and feed (Gatsby).
|
|
|
|
When documenting a feature, the source of truth for behaviour is `dc`. When a doc page describes internals, prefer linking to the user-facing concept rather than duplicating implementation detail.
|
|
|
|
## Structure
|
|
|
|
- Pages are Markdown files in `docs/`.
|
|
- The navigation tree, site config, theme, plugins and redirects are all defined in `mkdocs.yml`. **A new page is not published until it is added to the `nav:` tree in `mkdocs.yml`.**
|
|
- `docs/tables/` documents the `MPE_*` control tables (see naming conventions below).
|
|
- `docs/img/` holds images; `docs/video/` holds video assets; `docs/marketing/` holds flyers/PDFs.
|
|
- `theme/` is the custom Material theme override; `slides/` and `slides.md` are the presentation deck.
|
|
|
|
## Page conventions
|
|
|
|
- Each page starts with YAML front matter: `layout: article`, `title`, `description`, and usually `og_image`. Match the style of existing pages.
|
|
- `description` is used for SEO and social cards - write a single, complete sentence.
|
|
- Reference images with root-relative paths (e.g. `/img/foo.png`) or relative paths consistent with neighbouring pages.
|
|
- This site uses these `markdown_extensions`: `admonition`, `pymdownx.superfences`, `codehilite`, `meta`, and `toc` (with permalinks). Use fenced code blocks with language hints (`sas`, `js`, `bash` are highlighted); use admonitions (`!!! note`) for callouts.
|
|
- Internal links use the page slug with a trailing slash (e.g. `/dcc-validations/`), matching existing cross-references.
|
|
|
|
## MPE table docs (`docs/tables/`)
|
|
|
|
Control tables are documented one file per table, named `mpe_<name>.md`, and registered under the "Table Guide" section of `nav:` in `mkdocs.yml`. Follow the existing pattern:
|
|
|
|
- Front matter with a `description` explaining what the table configures.
|
|
- A short intro paragraph, then a link to the relevant configuration guide.
|
|
- A `## Columns` list. Prefix primary-key / business-key columns with the 🔑 emoji, and give each column as `` `NAME type` ``: description. SCD2 tables carry `TX_FROM`/`TX_TO` as the first two columns.
|
|
|
|
## Writing style
|
|
|
|
Use regular dashes (`-`) in content, not em-dashes. Do not hard-wrap Markdown: each paragraph, list item and heading is a single logical line, regardless of length - let the renderer soft-wrap. This keeps diffs clean.
|
|
|
|
## Building
|
|
|
|
- `pip install mkdocs mkdocs-material mkdocs-redirects` (see `build.sh` / `mkdocs.yml` for the exact plugin list).
|
|
- `mkdocs serve` for a live-reloading local preview; `mkdocs build` (or `./build.sh`) to produce the static site.
|
|
- After adding or renaming a page, confirm it appears in the `nav:` tree and that `mkdocs build` reports no warnings about missing/orphaned files.
|
|
|
|
## Git
|
|
|
|
Do NOT auto-commit or push. Leave changes in the working tree for the user to review and commit.
|