docs: scrub em dashes, polish landing + nav#41
Merged
Conversation
Two small docs-site cleanups bundled in one PR. Em dashes (—) are a common LLM tell; the README scrub during PR #36 replaced them with commas, colons, semicolons, or sentence splits depending on context. Apply the same pass across every page under docs/. Total: 142 em dashes across 13 files, scrubbed without changing the prose's meaning. ``grep -c "—" docs/**/*.md`` returns zero across the tree. Pattern choice per occurrence: parentheticals (X — Y — Z) become parens or commas; definitions (X — body) become ``X: body``; two-clause sentences (X — Y) become sentence splits or semicolons; appositives become commas. Where the em dash was load- bearing in the prose rhythm, the sentence was rewritten rather than mechanically substituted. Also: the apex "specification" link on the docs landing page now opens in a new tab. attr_list is already enabled in mkdocs.yml, so ``{target="_blank" rel="noopener"}`` after the link does the job inline. uv run mkdocs build --strict clean.
The Contributing page was a one-paragraph stub saying "populated as concrete contributor-facing material accrues" — a dead click for any reader who landed on it. Until there's a real contributor pipeline, having no page is more honest than having an empty one. Deletes docs/contributing/ and its nav entry in mkdocs.yml. AGENTS.md remains the agent-facing orientation; if a real contributor doc is wanted later, it can be lifted from AGENTS.md selectively.
There was a problem hiding this comment.
Pull request overview
This PR polishes the MkDocs documentation site by standardizing prose punctuation (scrubbing em dashes), adjusting one landing-page outbound link to open in a new tab, and removing an unused/stub Contributing page from the nav.
Changes:
- Replaced em dashes across docs pages with alternative punctuation / sentence rewrites for more natural prose.
- Updated the landing-page “specification” link to open in a new tab via
attr_list. - Removed the stub Contributing page and its nav entry.
Reviewed changes
Copilot reviewed 14 out of 14 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| mkdocs.yml | Removes the Contributing nav entry. |
| docs/index.md | Tweaks landing copy punctuation and sets the specification link to open in a new tab. |
| docs/getting-started/index.md | Scrubs em dashes and adjusts list/link punctuation for readability. |
| docs/reference/index.md | Replaces em dash separators with colons in the reference index list. |
| docs/model-providers/index.md | Replaces em dash separators with parentheses/colons/semicolons in provider docs. |
| docs/model-providers/authoring.md | Replaces em dash separators with parentheses/periods for clearer list formatting. |
| docs/concepts/index.md | Replaces em dash separators with colons/semicolons in the concepts index list. |
| docs/concepts/graphs.md | Scrubs em dashes and adjusts punctuation in explanations and lists. |
| docs/concepts/state-and-reducers.md | Scrubs em dashes and adjusts punctuation in explanations and examples. |
| docs/concepts/composition.md | Scrubs em dashes and adjusts punctuation in explanations and lists. |
| docs/concepts/fan-out.md | Scrubs em dashes and adjusts punctuation in explanations and lists. |
| docs/concepts/observability.md | Scrubs em dashes and adjusts punctuation in explanations and lists. |
| docs/concepts/checkpointing.md | Scrubs em dashes and adjusts punctuation in explanations and lists. |
| docs/contributing/index.md | Deletes the stub Contributing page. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
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.
Summary
Three small docs-site cleanups, all surfaced in human review of the live site after PR #36 shipped.
Em dashes scrubbed across all docs pages
Em dashes (`—`) are a common LLM-output tell; the README rework (PR #36) replaced all 11 instances with commas, colons, semicolons, or sentence splits depending on context. Apply the same pass across every page under `docs/`.
Verification: `grep -c "—" docs/**/*.md` returns zero across the tree.
Specification link opens in a new tab
The "Built around an open, language-agnostic specification" link on `docs/index.md` now opens in a new tab. `attr_list` is already enabled in `mkdocs.yml`, so `{target="_blank" rel="noopener"}` after the link does the job inline.
Dropped the empty Contributing page
`docs/contributing/index.md` was a one-paragraph stub saying "populated as concrete contributor-facing material accrues" — a dead click. Until there's a real contributor pipeline, no page is more honest than an empty one. `AGENTS.md` remains the agent-facing orientation; a contributor-facing doc can be lifted later if/when wanted.
Test plan