docs: expand Claude Code docs, add Coder CLI page, replace outdated workspace guides

.github/workflows/docs-preview.yml

@@ -1,10 +1,14 @@
 name: Docs PR Preview
 
-# Deploys a preview of the /docs site to gh-pages at /pr-preview/pr-N/
-# and posts a comment with the URL on each PR.
-# On PR close, removes the preview automatically.
+# Posts one comment on each PR linking both previews:
 #
-# Preview URLs: https://start.coder.ddev.com/pr-preview/pr-<N>/
+# - start.coder.ddev.com landing pages (docs/*.html): built with Jekyll here and
+#   deployed to gh-pages at /pr-preview/pr-<N>/, with coder.ddev.com links
+#   pointed at staging-coder.ddev.com and docs.coder.ddev.com links pointed at
+#   this PR's Read the Docs preview. Removed again when the PR closes.
+# - docs.coder.ddev.com (docs/content): built by Read the Docs, not by this
+#   workflow, at https://coder-ddev--<N>.org.readthedocs.build/. Read the Docs
+#   also posts its own comment with build status and changed pages.
 
 on:
   pull_request:
@@ -18,6 +22,10 @@ concurrency:
   group: pr-preview-${{ github.event.number }}
   cancel-in-progress: true
 
+env:
+  LANDING_PREVIEW_URL: https://start.coder.ddev.com/pr-preview/pr-${{ github.event.number }}/
+  DOCS_PREVIEW_URL: https://coder-ddev--${{ github.event.number }}.org.readthedocs.build/
+
 jobs:
   preview:
     runs-on: ubuntu-latest
@@ -34,17 +42,51 @@ jobs:
           source: ./docs
           destination: ./_site
 
-      - name: Point preview at staging-coder.ddev.com
+      - name: Point preview at staging-coder.ddev.com and the docs preview
         if: github.event.action != 'closed'
         run: |
           cp -r ./_site ./_site_preview
-          find ./_site_preview -name "*.html" -exec sed -i 's|https://coder\.ddev\.com|https://staging-coder.ddev.com|g' {} +
+          find ./_site_preview -name "*.html" -exec sed -i \
+            -e 's|https://coder\.ddev\.com|https://staging-coder.ddev.com|g' \
+            -e "s|https://docs\.coder\.ddev\.com/|${DOCS_PREVIEW_URL}|g" {} +
 
-      - name: Deploy PR preview
+      - name: Deploy or remove landing-page preview
         uses: rossjrw/pr-preview-action@v1
         with:
           source-dir: ./_site_preview
           preview-branch: gh-pages
           umbrella-dir: pr-preview
+          pages-base-url: start.coder.ddev.com
           token: ${{ secrets.GITHUB_TOKEN }}
           action: auto
+          # The combined comment below replaces the action's own comment
+          comment: false
+
+      - name: Comment with both preview links
+        if: github.event.action != 'closed'
+        uses: marocchino/sticky-pull-request-comment@v2
+        with:
+          # Same header the preview action used for its comment, so this
+          # replaces that comment on PRs that already have one
+          header: pr-preview
+          message: |
+            ### Previews
+
+            | Site | Preview |
+            | ---- | ------- |
+            | **docs.coder.ddev.com** (`docs/content`, built by Read the Docs) | ${{ env.DOCS_PREVIEW_URL }} |
+            | **start.coder.ddev.com** (`docs/*.html`, deployed to `gh-pages`) | ${{ env.LANDING_PREVIEW_URL }} |
+
+            The landing-page preview creates workspaces on staging-coder.ddev.com, and its Documentation links open the docs preview. Read the Docs posts its build status and changed pages in its own comment; the docs preview may take a minute or two after a push to update.
+
+            <sub>Updated for ${{ github.event.pull_request.head.sha }}</sub>
+
+      - name: Update comment when the PR closes
+        if: github.event.action == 'closed'
+        uses: marocchino/sticky-pull-request-comment@v2
+        with:
+          header: pr-preview
+          message: |
+            ### Previews
+
+            The start.coder.ddev.com landing-page preview has been removed. Read the Docs keeps or removes its own docs preview.

docs/content/freeform/create.md

@@ -42,7 +42,7 @@ Off by default. Turn it on to have this workspace run sessions you start on clau
 
 ## From the command line
 
-With the [Coder CLI](https://coder.com/docs/install/cli) logged in to coder.ddev.com:
+With the [Coder CLI](../workspaces/coder-cli.md) logged in to coder.ddev.com:
 
 ```bash
 coder create --template freeform my-workspace

docs/content/freeform/first-project.md

@@ -6,7 +6,7 @@ This walkthrough takes you from an empty workspace to a running site. It assumes
 
 On the workspace page, click **VS Code**. When it opens, choose **Terminal → New Terminal** from the menu (☰). VS Code opens in `~/my-site`, a directory named after the workspace; it may not exist yet, in which case VS Code opens your home directory.
 
-You can also use SSH from your computer. See [Editors, SSH and files](../workspaces/editors-and-ssh.md).
+You can also use SSH from your computer. See [Using the Coder CLI](../workspaces/coder-cli.md#ssh-into-a-workspace).
 
 ## 2. Get your code
 

docs/content/getting-started/access.md

@@ -29,10 +29,10 @@ If you see an "access denied" page, your GitHub account isn't in one of the orga
 
 ## Use the CLI (optional)
 
-The [Coder CLI](https://coder.com/docs/install/cli) lets you SSH into workspaces, copy files, and connect desktop editors.
+The [Coder CLI](../workspaces/coder-cli.md) lets you SSH into workspaces, copy files, and connect desktop editors.
 
 ```bash
 coder login https://coder.ddev.com
 ```
 
-This opens your browser to approve the login. See [Editors, SSH and files](../workspaces/editors-and-ssh.md) for what you can do next.
+This opens your browser to approve the login. See [Using the Coder CLI](../workspaces/coder-cli.md) for how to install it and what you can do with it.