Background
docs/ currently serves double duty:
start.coder.ddev.com — custom HTML web app (landing page index.html, issue picker drupal-issue.html, CNAME, _config.yml). This is deployed via GitHub Pages from main/docs.- Markdown documentation —
docs/user/, docs/admin/, docs/architecture/ added later as contributor/admin reference. These get rendered by Jekyll with default styling that clashes with the custom HTML pages.
The two uses conflict. Jekyll renders everything in docs/, so the markdown files are technically published to start.coder.ddev.com/user/getting-started etc., but with inconsistent styling.
Tasks
1. Sort out docs in GitHub Pages
Options to evaluate:
- Move markdown docs out of
docs/ — e.g., to a top-level developer-docs/ or keep alongside CLAUDE.md. They remain readable on GitHub via relative links from the README. docs/ becomes purely the web app. Simplest option.
- Build a proper Jekyll theme that unifies the custom HTML and rendered markdown under a consistent style. More work, better result.
- Use a separate docs platform — GitHub Wiki, or a second GH Pages source (requires a separate branch or repo). Probably overkill.
The markdown docs are primarily for contributors and administrators — GitHub file browsing may be sufficient and a full web publication may not be needed.
2. Provide start.staging-coder.ddev.com
The issue picker at start.coder.ddev.com/drupal-issue points at coder.ddev.com (production). For testing template changes on staging-coder.ddev.com, a staging equivalent is needed so the issue picker can be tested end-to-end without touching production.
Options to evaluate:
- Second CNAME / subdomain — add
start.staging-coder.ddev.com DNS entry pointing at GitHub Pages. GitHub Pages supports only one custom domain per repo, so this may require a separate approach.
- Staging branch — a
staging branch with its own docs/ that has a different CNAME (start.staging-coder.ddev.com) and points the issue picker JS at staging-coder.ddev.com. GitHub Pages would need to be configured for that branch.
- Separate repo —
ddev/coder-ddev-staging with its own Pages deployment. Heavyweight.
- Query parameter / environment toggle — the issue picker HTML could accept a
?coder_url= parameter so testing against staging is possible without a separate deployment.
The query parameter approach is the lightest lift and enables immediate staging testing without any DNS or Pages changes.
Related
Background
docs/currently serves double duty:start.coder.ddev.com— custom HTML web app (landing pageindex.html, issue pickerdrupal-issue.html, CNAME,_config.yml). This is deployed via GitHub Pages frommain/docs.docs/user/,docs/admin/,docs/architecture/added later as contributor/admin reference. These get rendered by Jekyll with default styling that clashes with the custom HTML pages.The two uses conflict. Jekyll renders everything in
docs/, so the markdown files are technically published tostart.coder.ddev.com/user/getting-startedetc., but with inconsistent styling.Tasks
1. Sort out docs in GitHub Pages
Options to evaluate:
docs/— e.g., to a top-leveldeveloper-docs/or keep alongsideCLAUDE.md. They remain readable on GitHub via relative links from the README.docs/becomes purely the web app. Simplest option.The markdown docs are primarily for contributors and administrators — GitHub file browsing may be sufficient and a full web publication may not be needed.
2. Provide
start.staging-coder.ddev.comThe issue picker at
start.coder.ddev.com/drupal-issuepoints atcoder.ddev.com(production). For testing template changes onstaging-coder.ddev.com, a staging equivalent is needed so the issue picker can be tested end-to-end without touching production.Options to evaluate:
start.staging-coder.ddev.comDNS entry pointing at GitHub Pages. GitHub Pages supports only one custom domain per repo, so this may require a separate approach.stagingbranch with its owndocs/that has a different CNAME (start.staging-coder.ddev.com) and points the issue picker JS atstaging-coder.ddev.com. GitHub Pages would need to be configured for that branch.ddev/coder-ddev-stagingwith its own Pages deployment. Heavyweight.?coder_url=parameter so testing against staging is possible without a separate deployment.The query parameter approach is the lightest lift and enables immediate staging testing without any DNS or Pages changes.
Related