dagster-docs

---
name: dagster-docs
description:
  Expert guidance for writing documentation for the Dagster docs website. ALWAYS use before creating or updating
  documentation in the docs directory.
---

## Overview

### Prerequisites

- Always ensure `docs/node_modules` exists before running any commands
  - **Check first**: Look for `docs/node_modules/` directory
  - **If missing**: Run `yarn install` in `/docs` to install dependencies
  - **Command**: `cd /docs; yarn install`

- Always ensure `docs/docs/api/**/*.mdx` files exist before running `yarn start`
  - **Check first:** Look for `docs/docs/api/**/*.mdx` files
  - **If missing:** Run `yarn build-api-docs` in the docs root
  - **Command:** `cd /docs; yarn build-api-docs`

### Related documentation

- **Audiences:** See `audiences.md` for descriptions of primary audiences.
- **Formatting and style:** See `docs/docs/about/contributing-docs/formatting-style.md` for formatting and style conventions.
- **Content model:** See `docs/docs/about/contributing-docs/content-model` for an explanation of the structure and types of content included in Dagster docs.

---

## Section-specific guidance

### `docs/docs/about`

#### Audiences

All

#### Guidance

`docs/docs/about/changelog.md` is automatically populated from `/CHANGES.md` through a custom React component. Do not edit `changelog.md` directly.

### `docs/docs/api`

#### Audiences

- Data pipeline builders
- Data platform owners

#### Guidance

`.mdx` files are generated from `.rst` files in
`docs/sphinx/sections/api` and should not be directly edited. Instead, update the `.rst` file or the docstrings in `/python_modules`.

### `docs/docs/dagster-basics-tutorial`

#### Audiences

- Data pipeline builders

### `docs/docs/deployment`

#### Audiences

- Data platform owners

### `docs/docs/examples`

#### Audiences

- Data pipeline builders

#### Examples

- `docs/docs/examples/full-pipelines/bluesky`

### `docs/docs/getting-started`

#### Audiences

- Data pipeline builders

### `docs/docs/guides`

#### Audiences

- Data pipeline builders

#### Guidance

Most subdirectories in `docs/docs/guides` correspond to phases in the data engineering lifecycle:

- **Build:** Creating data pipelines with core Dagster abstractions, particularly projects, assets, resources, and components.
- **Automate:** Automating data pipelines with declarative automation, schedules, and sensors.
- **Operate:** Managing pipeline operations with run configuration, environment variables and secrets, and concurrency.
- **Log and debug:** Understanding built-in structured event logs and raw compute logs, configuring custom loggers, capturing Python logs, and debugging assets during execution with `pdb`.
- **Observe:** Using alerts, the Dagster+ asset catalog, asset freshness policies, and Insights to observe data pipelines.
- **Test:** Testing assets and pipelines in Dagster to ensure data remains consistent and fresh.

The `docs/docs/guides/labs` subdirectory contains documentation of new features under active development. All pages in the Labs section should import the early access partial and reference it at the top of the page.

The `docs/docs/partials` subdirectory contains files with text that is referenced in multiple places throughout the documentation.

#### Examples

- `docs/docs/guides/build/assets/asset-selection-syntax`
- `docs/docs/guides/automate/declarative-automation`

### `docs/docs/integrations`

#### Audiences

- Data pipeline builders

#### Guidance

- `.mdx` files are generated from `.rst` files in `sphinx/sections/integrations` and should not be directly edited. Instead, update the corresponding `.rst` file. Docstrings for classes and modules in corresponding files in `python_modules/libraries` may also need to be updated.
- If an integration has a component implementation, the component documentation should be placed in the index page of the integration subdirectory

#### Examples

- `docs/docs/integrations/libraries/databricks`
- `docs/docs/integrations/libraries/fivetran`

### `docs/docs/migration`

#### Audiences

- Data pipeline builders
- Data platform owners

#### Guidance

- `docs/docs/migration/upgrading.md` is automatically populated by `/MIGRATION.md` through a custom React component. Do not edit `upgrading.md` directly.

---

## Verification

1. `yarn start` in `/docs` directory
2. Navigate to http://localhost:3050 and view changed pages