DDEV Website for Contributors

The following is based on Matt Stein’s presentation outline for the August 15, 2023 DDEV contributor training. Recordings of all past sessions can be found in the blog post DDEV Contributor Live Training. This post was prepared (Thanks!) by Kristin Wiseman.

Welcome!

I’d like to show you how ddev.com is put together so you can swoop in and improve it. There’s a lot that could be improved; The emphasis is on “what it is” rather than “how it should be.”

Background

Old Things

Matt is a designer that’s been doing CMS-based development for clients using PHP, Twig, and different front-end frameworks; master of none fond of writing, documentation, and content strategy.

ddev.com is a former WordPress site, tricky to share access and not the friendliest public welcome to all things DDEV.

New Thing

Rebuilt + migrated earlier this year to Astro!

• Hat tip Mayank for sharing Astro with me.
• Fun to build with!
• Static site generator that sits in a nice front-end sweet spot.
  • Flat file + fully accessible to front-end developers in a public repository.
  • Friendly to Markdown-writers.
  • Key feature: Astro components!
    • .astro, or BYO UI framework (Vue, React, Svelte, etc.).
    • Or no UI framework; only ship what’s necessary for the viewer.
    • “island architecture”
  • HTML and simple components.
  • Markdown content collections.
  • Tailwind CSS + Tailwind Typography.
  • Built and hosted with Cloudflare Pages.

tl;dr if you’re comfortable with Markdown, HTML, CSS, Tailwind, or a modern front-end framework, you can jump right in!

Also TypeScript, kind of.

If you’re comfortable with all of those things, you could make a big dent in ddev.com.

Local Setup

Clone https://github.com/ddev/ddev.com.

Add a GitHub key to .env.

Where Content Lives

💡 Consider reading the readme and especially the Astro docs.

Markdown, component markup, TypeScript constants, and a JSON blob.

1. Astro components in the src/pages/ directory.
   • Start with 404 + homepage.
2. Content collections in src/content/.
3. Constants in src/const.ts.
4. Custom sponsor blob in src/featured-sponsors.json.
   • See featured-sponsors.svg in the ddev/ddev readme.

How Content is Presented

The content attempts to follow Astro conventions, follow DRY principle, and be sparing with additional complexity.

1. Astro config.
2. PostCSS + Tailwind + Tailwind Typography
3. src/lib/api.ts.
   • Bonus: the cache/ directory.
4. Development server vs. building.
   • Cloudflare pages builds static output (no SSR).
   • Run locally for previewing and instant feedback, but production and preview branches are built automatically (similar to Netlify and Vercel).

Submitting Changes

Typo corrections can be done directly from the GitHub UI similarly to fixing the docs.

Otherwise, use a pull request like you would with DDEV or any other project. (Fork, change, submit pull request.)

Extra Topics Covered in the Training

• Astro plugins we’re using.
• Textlint.

Credit to Kristin and Bernardo for adapting the original outline for the DDEV blog.