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 used to be a WordPress site, tricky to share access and not the friendliest public welcome to all things DDEV.

New Thing

Rebuilt + migrated in 2023 to Astro!

• Hat tip to 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! Blog posts and edits are even easier than that.

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. (optional)

Where Content Lives

💡 Read 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.