[rfay]

Short Summary (TL;DR)

Moves the Markdown docs into a Zensical site, set up the same way as ddev/ddev's, to be published by Read the Docs at docs.coder.ddev.com. Adds user docs for hosted coder.ddev.com, including a freeform guide, and puts a Documentation button at the top of start.coder.ddev.com.

The Issue

Jekyll rendered the Markdown docs on start.coder.ddev.com with no navigation or search, and the landing page linked only the Drupal quickstart. Freeform had no user guide, and its README was out of date: it still described single-project URLs and showed enable_adminer as a user choice, but it is an admin-only template variable. User and admin material were mixed together.

How This PR Solves The Issue

• The docs move to docs/content/ with a root mkdocs.yml, docs/requirements.txt and .readthedocs.yaml, all taken from ddev/ddev. GitHub Pages serves one custom domain per repository, and start.coder.ddev.com keeps it for the landing pages and deep-link builders.
• New pages for coder.ddev.com users: getting started, access, choosing a template, the freeform guide (every parameter, first project, multiple projects, recipes, services and add-ons, sharing), workspace lifecycle (persistence, the idle-deletion policy, the startup hook, disk), editors/SSH/files, Claude Code and troubleshooting. Existing docs move under Drupal, Reference and Self-Hosting. The Drupal quickstart's links to the issue and core pickers now point to start.coder.ddev.com, since the page no longer lives on that site.
• Landing page: a top bar with a Documentation button, docs links in the intro box, the freeform tile and Resources, and a Documentation link in the drupal-issue and drupal-core page headers. Jekyll excludes docs/content/, and jekyll-redirect-from stubs send the old /user/*, /admin/*, /architecture/* and /reference/* URLs to the new pages.
• freeform/README.md is cut down to a contributor summary that links to the docs. README and AGENTS.md now describe the two sites and the docs checks.

Manual Testing Instructions

• Open the Read the Docs PR preview and check the navigation, search and the freeform pages.
• Open the start.coder.ddev.com PR preview. The Documentation button should be at the top, and /user/quickstart should redirect to https://docs.coder.ddev.com/drupal/quickstart/.
• On staging-coder.ddev.com, follow the freeform pages: create a workspace with two project names, then do the first project, add a second project, try a few recipes and turn on Public Sharing. The recipes, especially WordPress, Node.js and Vite, have not been run in a workspace yet.

Automated Testing Overview

A new docs-check.yml workflow runs zensical build --strict, markdownlint (ddev's .markdownlint.jsonc), linkspector and scripts/check-doc-params.sh. That script fails when a param.<name> deep link under docs/ names a coder_parameter that no template or shared module defines. make docs-check runs the same checks locally, except linkspector. Fixing the existing docs for markdownlint also fixed lists and code blocks that were rendering as plain paragraphs. Dead external links were fixed, and a full local linkspector run (0.5.6, all pages rather than only added lines) reports every link valid. The coder-ddev-com message templates are excluded from linkspector because they contain placeholder URLs by design.

Release/Deployment Notes

Before merging, create a Read the Docs project for ddev/coder-ddev with PR builds and single-version URLs, add the custom domain docs.coder.ddev.com, and add the DNS CNAME. Until then, the redirect stubs on start.coder.ddev.com point at a domain that doesn't resolve.

🤖 Developed with assistance from Claude Code

https://claude.ai/code/session_01UrTUMw3UoHt66UH5tSoYTd

[github-actions]

PR Preview Action v1.8.2
Preview removed because the pull request was closed.
2026-11-05 15:48 UTC