zaduma

zaduma is an Astro starter template for understated personal websites, pairing SolidJS, MDX, Tailwind CSS, and Vercel OG to power a minimal blog with dynamic Open Graph images.

What is zaduma?

zaduma is a starter template built with the Astro framework that generates a static blog from MDX posts. It takes posts written in MDX with frontmatter as input and produces a deployable static site with a post index page, individual post pages, and dynamically generated Open Graph images via Vercel OG. The template is available as a GitHub template under the hasparus account.

Key Features

• Astro framework — The site is built with Astro, allowing static generation and CLI commands like astro add and astro check.
• SolidJS integration — Interactive components can be written in SolidJS alongside Astro pages.
• MDX posts — Write posts in MDX (Markdown with JSX), processed through Remark and Unified, enabling interactive content inside Markdown files.
• Shiki Twoslash highlighting — Code blocks are rendered with Shiki Twoslash, which displays type information on hover for TypeScript examples.
• Tailwind CSS styling — Tailwind CSS is configured in tailwind.config.cjs with custom colors and fonts; global styles live in src/global-styles/.
• Vercel OG dynamic images — Open Graph images are generated on demand for each post through a Vercel OG endpoint protected by an OG_IMAGE_SECRET.
• GitHub Actions deployment — A CI workflow in workflows/ci.yml builds and deploys to Vercel using VERCEL_TOKEN, VERCEL_PROJECT_ID, and VERCEL_ORG_ID secrets.
• Playwright tests — The repository includes an e2e directory and playwright.config.ts for end-to-end testing.

Who is it for?

• Developer-bloggers — People who want a clean, minimal blog where they can write technical posts and showcase code with the added benefit of Twoslash type tooltips.
• Astro users — Those already comfortable with Astro who want a preconfigured project structure with SolidJS and MDX integrated, rather than starting from scratch.
• Design-focused personal site owners — Individuals who prefer an understated aesthetic built with Tailwind CSS and no heavy JavaScript by default.

What can you do with zaduma?

• Publish MDX posts — Drop a .mdx file into the posts/ directory with frontmatter such as date, and it automatically appears on the index page and gets a dedicated route via the [path].astro dynamic route.
• Generate Open Graph images — Each post gets a dynamically generated social preview image through the Vercel OG integration, secured by an OG_IMAGE_SECRET you define.
• Deploy with Git history — Using the included GitHub Actions workflow with Vercel secrets, the build can read git log to derive post dates when they aren't provided in frontmatter.

How does zaduma work?

1. Click Use this template on GitHub to create a new repository.
2. Install dependencies with pnpm install and start developing with pnpm run dev (dev server runs at localhost:3000).
3. Write MDX files in posts/. If a post lacks a date, the template uses execSync("git log") to infer it.
4. To deploy, set the three Vercel secrets and OG_IMAGE_SECRET in GitHub Actions settings.
5. Remove the e2e directory and playwright.config.ts if you don't need the Playwright tests.

FAQ

Does zaduma require pnpm?

The documented commands in the README use pnpm (such as pnpm install and pnpm run dev), so pnpm is the recommended package manager for this starter.

Can I connect my own Vercel project instead of using GitHub Actions?

Yes. If every post has a date in frontmatter, you can skip the workflow's deploy steps, remove the execSync("git log") call from derivedTitleAndDatePlugin, and connect Vercel or Netlify directly through their integrations.

What is the OG_IMAGE_SECRET used for?

It secures the Vercel OG endpoint that generates Open Graph images. You create a passphrase and store it as a GitHub Actions secret to prevent unauthorized image generation on your public URL.

How do I change the site's fonts and colors?

Global font, body, and prose styles are in src/global-styles/, and Tailwind's theme (colors, fonts) is configured in tailwind.config.cjs. Layout files BaseLayout.astro and PostLayout.astro control the shared page structure.