Skip to content

feat(docs): guided start pages and landing UX for Drupal workspaces#167

Merged
rfay merged 21 commits into
mainfrom
fix/156-landing-ux
Jun 30, 2026
Merged

feat(docs): guided start pages and landing UX for Drupal workspaces#167
rfay merged 21 commits into
mainfrom
fix/156-landing-ux

Conversation

@rfay

@rfay rfay commented Jun 29, 2026

Copy link
Copy Markdown
Member

Note: This is a copy of #157 (by @jameswilson), rebased onto main so CI can run. The original PR was submitted from a fork where GitHub Actions are blocked for first-time contributors. All commits and authorship are preserved.

Fixes #156

Summary

Users landing on start.coder.ddev.com were often sent straight to the raw drupal-core Coder template in manual mode, where version/branch mismatches and opaque parameter choices caused confusion. This PR steers people through guided entry points on the start site, consolidates shared styling, and prefills workspace creation via mode=auto so the right template parameters are locked in before Coder opens.

Landing page (docs/index.html)

  • Replaces the old single-call-to-action layout with a two-column tile grid: Drupal Issue (recommended) and DDEV Freeform
  • Adds footnote-linked callouts for stability expectations and GitHub OAuth access requirements
  • Moves sign-in guidance below the primary tiles in a muted callout with GitHub icon
  • Links "How it works" and resources to the new guided pages instead of raw template URLs
  • Point core contribution environment (or a simple clean Drupal demo environment) to /drupal-core from /drupal-issue.
  • Fixes malformed footnote markup (stray closing </a>)

New guided start pages

/drupal-core (docs/drupal-core.html)

  • New page for vanilla Drupal core workspaces (no issue fork)
  • Pick-card radios for Drupal version (10/11/12), install profile (Demo Umami / Minimal / Standard), and site visibility
  • Editable workspace name with live URL slug preview
  • Launches coder/drupal-core with mode=auto and disable_params so version, profile, and visibility are prefilled and not accidentally changed in Coder

/drupal-issue (docs/drupal-issue.html)

  • Major refactor aligned with the drupal-core page layout and copy
  • Accepts issue number, drupal.org issue/project URL, or contrib machine name
  • Issue flow: fetches issue metadata from drupal.org, loads branches from git.drupalcode.org, auto-selects the most recently committed branch, and chooses drupal-core vs drupal-contrib template automatically
  • Plain contrib flow: verify project on git.drupalcode.org, then launch HEAD development without an issue fork
  • Manual fallback form when APIs fail (fork name, branch, version, profile, visibility)
  • Pick-card fields replace <select> dropdowns for version, profile, and site visibility (matches drupal-core)
  • Launches with mode=auto + disable_params on all three forms (result, plain, manual)
  • Theme support: resolves param.project_type (module vs theme) from the Drupal.org project node API (project_theme / project_module) so contrib themes symlink into web/themes correctly
  • Template badge shows project type for contrib issues

Shared infrastructure

docs/coder-ddev-start.css

  • New shared design system for the start site (~1500 lines): dark hero, tile grid, pick-cards, callouts, form fields, status messages, footnotes, accessibility helpers
  • Component classnames are prefixed with .cds- namespace
  • Replaces large inline <style> blocks previously duplicated across pages

docs/coder-workspace-name.js

  • Shared workspace name sanitization and suggestion helpers
  • 32-character Coder workspace name limit with inline field validation before launch
  • Branch-based names fall back to issue NID when {version}-{profile}-{branch} would exceed the limit

docs/components.html

  • Internal component gallery documenting pick-cards, tiles, callouts, and form patterns used on the start site

Layout consolidation

  • docs/_layouts/default.html, docs/access-denied.html — drop inline CSS in favor of shared stylesheet
  • New logo assets: docs/logo-coder-on-dark.svg, docs/logo-ddev-on-dark.svg

Documentation updates

docs/user/quickstart.md

  • Replaces raw "Open in Coder" button with guided tile links to /drupal-issue and /drupal-core
  • Adds guidance about confirming workspace creation in Coder vs editing locked parameters
  • Links code layout sections to ddev-drupal-dev and ddev-drupal-contrib add-on documentation via announce callouts

README.md

  • Replaces single manual template badge with recommended paths (issue picker, freeform, guided core, template browser) and an advanced manual link

Template tweak (requires separate template push)

drupal-core/template.tf

  • Human-readable install profile option labels (Demo Umami, Minimal, Standard)
  • Clearer install profile description explaining Demo Umami snapshot behavior on Drupal 12 vs full installs on other profiles/versions

Note: The template.tf label/description changes only take effect after the template is pushed to Coder; the start-site UX changes deploy with GitHub Pages.

Test plan

  • Load start.coder.ddev.com/ — two tiles render; Drupal tile goes to /drupal-issue; footnotes link and scroll correctly
  • /drupal-issue — core issue (e.g. drupal.org core issue NID): loads branches, launches drupal-core template
  • /drupal-issue — contrib module issue: launches drupal-contrib with param.project_type=module
  • /drupal-issue — contrib theme (e.g. olivero or theme issue): launches with param.project_type=theme
  • /drupal-issue — plain contrib machine name: plain-dev form, correct project type in URL
  • /drupal-issue – links to /drupal-core in an info box near the top of the page
  • /drupal-core — pick version/profile/visibility, launch URL contains mode=auto and expected param.* values
  • Workspace name > 32 chars blocked with inline error; branch-based fallback uses NID
  • Jekyll quickstart page renders tile HTML and announce callouts
  • terraform fmt / validate on drupal-core if template push is included in this release

🤖 Generated with Claude Code

@github-actions

github-actions Bot commented Jun 29, 2026

Copy link
Copy Markdown
PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-06-30 02:59 UTC

@rfay rfay force-pushed the fix/156-landing-ux branch 3 times, most recently from 8c8754d to 3c6befe Compare June 29, 2026 21:12
jameswilson and others added 21 commits June 29, 2026 15:55
Add pick-card controls, dark tokens, and logo assets; document patterns on /components.html.
Replace inline CSS on index, access-denied, and the default Jekyll layout with coder-ddev-start.css.
Use pick-card fields for version, profile, and site visibility; launch workspaces via mode=auto with prefilled params.
Point users at the issue picker and Drupal core start flows instead of a raw Open in Coder link.
Add a three-column hero layout, callout variants, and move sign-in guidance below the primary entry tiles.
Style footnote links with target flash, move access details to a second footnote, and fix notes section markup.
Fall back to issue NID when branch-based names exceed the limit and show inline field errors before launch.
Use announce callouts for ddev-drupal-dev and ddev-drupal-contrib documentation.
Point the Drupal Core tile at /drupal-core and remove a stray closing anchor tag.
Resolve module vs theme from the Drupal.org project node API so drupal-contrib
launch URLs symlink themes into web/themes instead of web/modules.
…verflow

- buildContribIssueUrl was passing currentNid as param.issue_fork instead
  of currentIssueFork (the fork name string like token-3568144); every
  contrib issue workspace launch was sending the wrong value
- openManualWorkspace was passing nidFromFork instead of the full fork name
- fetchDrupalOrgProjectType now returns null on failure instead of silently
  returning 'module'; loadIssue and loadPlainProject warn the user, and
  openManualWorkspace shows a visible status message before launching
- suggestedIssueForkWorkspaceName now bounds-checks the NID fallback path
  and truncates to MAX_WORKSPACE_NAME_LENGTH to prevent server-side rejection
- CORE_DISABLE_PARAMS moved to coder-workspace-name.js and imported by
  both drupal-core.html and drupal-issue.html, eliminating the duplicate

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…olumn grid

The Drupal Issue picker covers the same use cases, making the Drupal Core
tile redundant. Also removes the orphaned "Drupal core template includes"
section and updates the "How it works" step to drop the drupal-core link.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
jekyll-build-pages runs as root in Docker so sed -i cannot create temp
files. chmod -R a+w before the find/sed fixes it.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
jekyll-build-pages creates files owned by root; chmod and sed -i both
fail. Copying to a new directory transfers ownership to the runner,
making in-place sed edits work.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Absolute /drupal-issue breaks on GitHub Pages PR previews where
the base path is not the root. Relative drupal-issue works in
both production and preview environments.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
/favicon.svg and href="/" break on GitHub Pages PR previews where
the base path is not the server root. Use favicon.svg and href="."
so all links resolve correctly in both production and preview.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
The cp and find commands were attached to the if: key as malformed
YAML, so _site_preview was never created and the deploy step had no
source to push.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@rfay rfay force-pushed the fix/156-landing-ux branch from 4a525c9 to 619058b Compare June 29, 2026 21:55
@rfay

rfay commented Jun 29, 2026

Copy link
Copy Markdown
Member Author

I think this is doing what it should be doing now, thanks for this @jameswilson !

@rfay rfay requested a review from jameswilson June 30, 2026 02:57
@rfay rfay merged commit 280b263 into main Jun 30, 2026
24 of 30 checks passed
@rfay rfay deleted the fix/156-landing-ux branch June 30, 2026 02:59

@jameswilson jameswilson left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Improve landing-page UX and CTAs to reduce version/branch mismatch confusion

2 participants