Repository navigation
docs: expand Claude Code docs, add Coder CLI page, replace outdated workspace guides - #233
Merged
Merged
Conversation
Documentation build overview
12 files changed ·
|
PreviewsThe start.coder.ddev.com landing-page preview has been removed. Read the Docs keeps or removes its own docs preview. |
…orkspace guides ## Short Summary (TL;DR) Expands the Claude Code page (terminal, VS Code extension, tips for DDEV projects), adds a "Using the Coder CLI" page that links to Coder's docs, and replaces the two guides carried over from the old docs, which gave wrong instructions for coder.ddev.com. ## The Issue A walk through the live docs.coder.ddev.com found: - The Claude Code page covered only remote control and the self-hosted runner, not using Claude Code in a terminal or in VS Code. - There was no single page on the local `coder` CLI; its commands were scattered across several pages. - "Your first workspace" and the "Detailed workspace guide" came from the old self-hosting-oriented docs. They tell readers to ask an administrator for a server URL, choose CPU and memory, work in `~/projects/`, set `router_disabled: true` (which breaks freeform routing) and use port forwarding instead of the site's URL. - The `coder-ddev-com` message templates for org operators were published as pages, reachable through search and the sitemap. - The docs header had no way back to start.coder.ddev.com. ## How This PR Solves The Issue - `workspaces/ai-tools.md`: adds the four ways of using Claude Code side by side, logging in from a remote workspace, terminal use (including keeping a session alive in `tmux`), the VS Code extension in VS Code for Web and in desktop VS Code, tips for DDEV projects, and updating, alongside the existing remote-control and runner sections. - New `workspaces/coder-cli.md`: installing, logging in, managing workspaces, template updates, schedules, SSH, `config-ssh` with `scp`/`rsync`, port forwarding, `coder open`, connection troubleshooting and tokens, each linking to the matching page in Coder's docs. Every command was checked against `coder --help` (v2.38.2). `editors-and-ssh.md` now links to it instead of repeating it, and other pages' CLI links point to it. - `getting-started/first-workspace.md` is now a five-minute walkthrough on coder.ddev.com: create a freeform workspace, start a PHP site, open it, stop the workspace. - `workspaces/guide.md` is removed. Its coder.ddev.com-relevant content was already covered by the shorter pages, and the rest is generic DDEV material that docs.ddev.com covers. A redirect sends `workspaces/guide/` to the lifecycle page, and the start.coder.ddev.com stub for the old `/user/using-workspaces` URL now points there too. - `mkdocs.yml`: excludes the `coder-ddev-com` templates from the build, and adds a "Start a workspace" link to start.coder.ddev.com in the navigation. ## Manual Testing Instructions - Open the Read the Docs preview and read the Claude Code, Using the Coder CLI and Your first workspace pages. - Follow "Your first workspace" on coder.ddev.com or staging; it has not been run end to end. - Install the Claude Code extension in VS Code for Web as described. I confirmed it installs from the Marketplace that VS Code for Web uses, but did not open its panel in a browser. - Check that `https://docs.coder.ddev.com/workspaces/guide/` redirects to the lifecycle page after deploy. ## Automated Testing Overview `make docs-check` passes (strict Zensical build, markdownlint, deep-link parameters). A full local linkspector run (0.5.6) reports all links valid. A headless-browser walk of the live site found no broken in-page anchors, images or unrendered Markdown; in the rebuilt pages no code block scrolls horizontally at 1280px. 🤖 Developed with assistance from [Claude Code](https://claude.ai/code) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UrTUMw3UoHt66UH5tSoYTd
rfay
force-pushed
the
20261105_rfay_docs_claude_cli_cleanup
branch
from
November 5, 2026 16:20
ad9748c to
8b05573
Compare
The `Docs PR Preview` workflow commented only with the start.coder.ddev.com landing-page preview, and under its `ddev.github.io` address, which just redirects. Reviewers had to find the docs.coder.ddev.com preview in Read the Docs' own comment, and the landing preview's Documentation links still went to the production docs. - Turn off the preview action's own comment and post one sticky comment, under the same `pr-preview` header so it replaces the old comment, linking both previews: `https://coder-ddev--<N>.org.readthedocs.build/` for the docs and `https://start.coder.ddev.com/pr-preview/pr-<N>/` for the landing pages. When the PR closes, the comment says the landing preview was removed. - In the landing preview, rewrite `https://docs.coder.ddev.com/` links to the PR's Read the Docs preview, alongside the existing coder.ddev.com to staging rewrite. - Set `pages-base-url` so the action reports the start.coder.ddev.com address. Also from reviewing the Read the Docs preview of this PR: move the "Start a workspace" link from the Home section to the end of the navigation, so the footer's "Next" link on the home page no longer leaves the docs, and shorten a line in "Your first workspace" that reached the edge of its code block. 🤖 Developed with assistance from [Claude Code](https://claude.ai/code) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UrTUMw3UoHt66UH5tSoYTd
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.
Short Summary (TL;DR)
Expands the Claude Code page (terminal, VS Code extension, tips for DDEV projects), adds a "Using the Coder CLI" page that links to Coder's docs, and replaces the two guides carried over from the old docs, which gave wrong instructions for coder.ddev.com.
The Issue
A walk through the live docs.coder.ddev.com found:
coderCLI; its commands were scattered across several pages.~/projects/, setrouter_disabled: true(which breaks freeform routing) and use port forwarding instead of the site's URL.coder-ddev-commessage templates for org operators were published as pages, reachable through search and the sitemap.How This PR Solves The Issue
workspaces/ai-tools.md: adds the four ways of using Claude Code side by side, logging in from a remote workspace, terminal use (including keeping a session alive intmux), the VS Code extension in VS Code for Web and in desktop VS Code, tips for DDEV projects, and updating, alongside the existing remote-control and runner sections.workspaces/coder-cli.md: installing, logging in, managing workspaces, template updates, schedules, SSH,config-sshwithscp/rsync, port forwarding,coder open, connection troubleshooting and tokens, each linking to the matching page in Coder's docs. Every command was checked againstcoder --help(v2.38.2).editors-and-ssh.mdnow links to it instead of repeating it, and other pages' CLI links point to it.getting-started/first-workspace.mdis now a five-minute walkthrough on coder.ddev.com: create a freeform workspace, start a PHP site, open it, stop the workspace.workspaces/guide.mdis removed. Its coder.ddev.com-relevant content was already covered by the shorter pages, and the rest is generic DDEV material that docs.ddev.com covers. A redirect sendsworkspaces/guide/to the lifecycle page, and the start.coder.ddev.com stub for the old/user/using-workspacesURL now points there too.mkdocs.yml: excludes thecoder-ddev-comtemplates from the build, and adds a "Start a workspace" link to start.coder.ddev.com as the last navigation tab..github/workflows/docs-preview.yml: posts one PR comment linking both previews, the Read the Docs docs preview (https://coder-ddev--<N>.org.readthedocs.build/) and the start.coder.ddev.com landing preview, replacing the preview action's own comment. In the landing preview, Documentation links now open the PR's docs preview, alongside the existing coder.ddev.com to staging rewrite.Manual Testing Instructions
https://docs.coder.ddev.com/workspaces/guide/redirects to the lifecycle page after deploy.Automated Testing Overview
actionlint passes on
docs-preview.yml, and its link rewrite was tested locally on the landing page.make docs-checkpasses (strict Zensical build, markdownlint, deep-link parameters). A full local linkspector run (0.5.6) reports all links valid. A headless-browser walk of the live site found no broken in-page anchors, images or unrendered Markdown; in the rebuilt pages no code block scrolls horizontally at 1280px.🤖 Developed with assistance from Claude Code
https://claude.ai/code/session_01UrTUMw3UoHt66UH5tSoYTd