Docs: normalize heading underlines in getting_started/#2641
Merged
Conversation
Per the lightweight style guide proposed in #2460, RST heading underlines should follow the canonical hierarchy: - Page title: = - H1: ~ - H2: + - H3: ^ The pages under docs/getting_started/ used a mix of -/+/' for those levels. Remap them positionally per file (first level encountered becomes =, second becomes ~, etc.) so the rendered hierarchy matches the convention. Underline lengths and heading text are unchanged; only the underline character is swapped.
Contributor
Author
|
I have manually compared and confirmed the before-and-after and see no regression in the built docs. |
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates the reStructuredText heading underline characters across docs/getting_started/ to align with the proposed lightweight style guide hierarchy (page title =, H1 ~, H2 +, H3 ^), without changing heading text or underline lengths.
Changes:
- Normalized page titles to use
=underlines across getting started pages. - Remapped section headings to use
~(and subsections to+where applicable) to match the canonical hierarchy. - Kept heading text and underline lengths unchanged while swapping only the underline character.
Reviewed changes
Copilot reviewed 11 out of 11 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| docs/getting_started/oss-quickstart.rst | Normalizes title/section/subsection underline characters to the canonical hierarchy. |
| docs/getting_started/open-source.rst | Updates title and section underline characters to match the style guide. |
| docs/getting_started/mwaa.rst | Updates title and section underline characters to match the style guide. |
| docs/getting_started/index.rst | Updates title and section underline characters to match the style guide. |
| docs/getting_started/how-cosmos-works.rst | Updates title and section underline characters to match the style guide. |
| docs/getting_started/gcc.rst | Updates title and section underline characters to match the style guide. |
| docs/getting_started/dbt-airflow-concepts.rst | Updates page title underline character to match the style guide. |
| docs/getting_started/core-concepts.rst | Updates title/section/subsection underline characters to the canonical hierarchy. |
| docs/getting_started/bring-your-own.rst | Updates title and section underline characters to match the style guide. |
| docs/getting_started/astro.rst | Updates title and section underline characters to match the style guide. |
| docs/getting_started/astro-cli-quickstart.rst | Updates title and section underline characters to match the style guide. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
pankajastro
approved these changes
May 8, 2026
This was referenced May 8, 2026
pankajkoti
added a commit
that referenced
this pull request
May 11, 2026
## Description Per the lightweight style guide proposed in #2460, RST heading underlines should follow the canonical hierarchy: - Page title: `=` - H1: `~` - H2: `+` - H3: `^` The pages under `docs/optimize_performance/` used a mix of `-`/`+` for the title and H1 levels. Remap them positionally per file (first level encountered becomes `=`, second becomes `~`, etc.) so the rendered hierarchy matches the convention. Underline lengths and heading text are unchanged; only the underline character is swapped. Continues the underline-normalization work from #2641 (covered `getting_started/`). ## Related Issue(s) Refs #2460 ## Breaking Change? No. Documentation only. ## Checklist - [x] I have made corresponding changes to the documentation (if required) - [ ] I have added tests that prove my fix is effective or that my feature works
pankajkoti
added a commit
that referenced
this pull request
May 11, 2026
## Description Per the lightweight style guide proposed in #2460, RST heading underlines should follow the canonical hierarchy: - Page title: `=` - H1: `~` - H2: `+` - H3: `^` The pages under `docs/policy/` used a mix of `-`/`+`/`'` for those levels. Remap them positionally per file (first level encountered becomes `=`, second becomes `~`, etc.) so the rendered hierarchy matches the convention. Underline lengths and heading text are unchanged; only the underline character is swapped. Continues the underline-normalization work from #2641 (`getting_started/`) and #2655 (`optimize_performance/`). ## Related Issue(s) Refs #2460 ## Breaking Change? No. Documentation only. ## Checklist - [x] I have made corresponding changes to the documentation (if required) - [ ] I have added tests that prove my fix is effective or that my feature works
This was referenced May 12, 2026
tatiana
pushed a commit
that referenced
this pull request
May 12, 2026
Per the lightweight style guide proposed in #2460, RST heading underlines should follow the canonical hierarchy: - Page title: `=` - H1: `~` - H2: `+` - H3: `^` The pages under `docs/reference/` used a mix of `-`/`+` for those levels. Remap them positionally per file (first level encountered becomes `=`, second becomes `~`, etc.) so the rendered hierarchy matches the convention. Underline lengths and heading text are unchanged; only the underline character is swapped. Scope of this PR: - `docs/reference/configs/` — `cosmos-conf.rst`, `execution-config.rst`, `profile-config.rst`, `project-config.rst`. - `docs/reference/index.rst` — page title and the two H1 sections. - `docs/reference/templates/profile_mapping.rst.jinja2` — the "Default values" subheading, so the generated profile pages (Snowflake variants, etc.) emit the canonical H1 underline. `docs/reference/profiles/*.rst` is gitignored and regenerated from this template at docs build time. `docs/reference/glossary.rst` and the "Profile mapping reference" title in `templates/index.rst.jinja2` already use `=`, so they are unchanged. Continues the underline-normalization work from #2641 (`getting_started/`), #2655 (`optimize_performance/`), and #2656 (`policy/`). ## Related Issue(s) Refs #2460 --------- Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
tatiana
pushed a commit
that referenced
this pull request
May 12, 2026
Per the lightweight style guide proposed in #2460, RST heading underlines should follow the canonical hierarchy: - Page title: `=` - H1: `~` - H2: `+` - H3: `^` The pages under `docs/guides/` and the top-level `docs/index.rst` used a mix of `-`/`+`/`'`/`.` for those levels. Remap them positionally per file (first level encountered becomes `=`, second becomes `~`, third becomes `+`, fourth becomes `^`) so the rendered hierarchy matches the convention. Underline lengths and heading text are unchanged; only the underline character is swapped. Scope of this PR: - `docs/guides/connect_database/` (4 files) - `docs/guides/cosmos_devex/` (4 files) - `docs/guides/dbt_docs/` (2 files) - `docs/guides/dbt_setup/` (2 files) - `docs/guides/multi_project/` (1 file) - `docs/guides/run_dbt/airflow-worker/` (5 files) - `docs/guides/run_dbt/callbacks/` (1 file) - `docs/guides/run_dbt/container/` (8 files) - `docs/guides/run_dbt/customization/` (4 files) - `docs/guides/run_dbt/operators/` (4 files) - `docs/guides/run_dbt/execution-modes.rst`, `run_dbt/index.rst` (2 files) - `docs/guides/translate_dbt_to_airflow/` (6 files) - `docs/guides/index.rst` (1 file) - `docs/index.rst` (1 file) Wraps up the underline-character slice of the header commit in #2462 across the remaining `docs/` subtrees. Continues the work from #2641 (`getting_started/`), #2655 (`optimize_performance/`), #2656 (`policy/`), and #2663 (`reference/`). ## Related Issue(s) Refs #2460
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Per the lightweight style guide proposed in #2460, RST heading underlines
should follow the canonical hierarchy:
=~+^The pages under
docs/getting_started/used a mix of-/+/'for thoselevels. Remap them positionally per file (first level encountered becomes
=,second becomes
~, etc.) so the rendered hierarchy matches the convention.Underline lengths and heading text are unchanged; only the underline character
is swapped.
This is the first of several focused PRs covering the underline-character
slice of the header commit in #2462. Subsequent PRs will cover other
subdirectories under
docs/.Related Issue(s)
Refs #2460
Breaking Change?
No. Documentation only.
Checklist