# Open-Source Project Template — Research Brief

> **Assumption:** A small, single-author or small-team open-source CLI tool with broad developer appeal. Not a framework. Not a SaaS. A focused utility that solves one problem well and can be installed in one command.
>
> **Fictional project:** **`heron`** — a static-asset uploader for S3 / R2 / B2 with built-in deduplication and fingerprinted output paths. Written in Go. Solves a real, unsexy problem every frontend team eventually hits. Tag line: "Upload once. Never twice." Canonical install: `brew install heron` / `go install github.com/heron-cli/heron@latest` / `curl -fsSL https://get.heron.dev | sh`.
>
> **Why `heron` over `broom`:** `broom` (directory cleaner) is conceptually close to `rm -rf`. `heron` has a clearer value proposition for developers who already use S3-compatible object storage. More specific = more believable = better demo content.

---

## Audience & primary CTA

- **Who visits:** Backend and full-stack developers evaluating whether to add `heron` to a deploy pipeline. They arrive from a GitHub README link, a Hacker News thread, or a tweet. Dwell time is 60–90 seconds. They read the tagline, see the install command, scan the feature list, check the star count, and either run the install or open the GitHub repo.
- **Primary CTA:** Copy-to-clipboard install command (`brew install heron` / `go install ...` / `curl | sh`).
- **Secondary CTAs:** "View on GitHub" (top nav + hero) and "Read the Docs" (after the features section). No signup, no email collection — this niche does not expect it.

---

## Reference sites (real businesses)

- https://htmx.org — Opinionated plain-prose style; CDN snippet as install; retro ad banners inject personality; GitHub star link in nav; sponsor tiers prove sustainability. Moderate density. Light-default with monochrome.
- https://bun.sh — Dark navy/cream; hero is a single install command with platform toggle (macOS/Linux/Windows); "Used by" logo bar immediately after hero; benchmark tables as social proof; no contributors section but tweet carousel. High density in feature comparisons.
- https://vite.dev — Dark default; install snippet with tabbed package managers (npm / yarn / pnpm / bun / deno); "80k+ GitHub Stars" and "80M+ weekly npm downloads" as explicit metrics; "Used by" company logos; testimonial quotes. Clean section rhythm.
- https://oxc.rs — Dark with white text; hero states a category claim + two CTAs (Get Started / View on GitHub); six tool cards as features; benchmark chart as visual proof; tiered sponsor logos in footer. Tighter density.
- https://astro.build — Dark default; `npm create astro@latest` as hero CTA; "What is Astro?" section follows; performance metrics; ecosystem showcase; no prominent star count on homepage. Well-paced vertical rhythm.
- https://drizzle.team — Near-black dark; informal greeting in hero; product list as features; newsletter + socials; sponsor CTA. Very sparse — works because the brand is already established. Not a model for a new project.
- https://hono.dev — Ultra-minimal; tagline + multi-runtime list; two CTAs. Proves that small-footprint projects can have clean, confident landings without heavy sections.

---

## Existing templates surveyed

- AstroWind (github.com/arthelokyo/astrowind, 5.6k stars) — Generic SaaS/marketing. No install snippet component, no GitHub stars badge, no contributors widget, no copy-to-clipboard code block. Wrong shape for OSS.
- ScrewFast (github.com/mhyfritz/astro-landing-page) — Clean Tailwind bones. Light-default only. Missing all OSS-specific sections. Saturated pattern: hero + features + testimonials + pricing — doesn't map to OSS.
- StarFunnel (Astro landing page builder, 158 stars) — Adds Slack/Mailchimp integrations. Not useful for a static OSS landing; more oriented toward community growth tooling.
- Astro Themes "open-source" category — No dedicated OSS-project-marketing theme exists in the free tier as of May 2026. Category doesn't even appear in the directory. This is the gap.
- GitHub Pages auto-rendered READMEs — The de facto standard for small OSS projects. No visual identity, no install tabs, no star count, no contributors grid — just markdown on a gray background. Our template's clearest competitor and easiest win.
- **Saturated pattern:** Dark background + animated particle canvas + neon glow + vague "blazing fast" headline. Seen in Tailwind product templates everywhere. Avoids specificity, avoids personality.
- **Missing in free tier:** A single-page Astro template specifically shaped for OSS project marketing: install tabs, static star count + live badge, contrib.rocks contributors, Shiki code blocks, copy-to-clipboard, schema.org `SoftwareSourceCode`, GH Pages wiring. Nothing ships all of this free.

---

## Must-have sections (in order)

1. **Hero** — Project name + one-line tagline. Tabbed install snippet (brew / go install / curl). "View on GitHub" ghost button. Static star count as text badge ("★ 2.1k") + shields.io live SVG as img (fallback to static if it fails).
2. **Features** — 4–6 cards. Icon (inline SVG) + title + 2-line description. Grid layout (2-col mobile, 3-col desktop). No generic SaaS features — every item is `heron`-specific and technically credible.
3. **How it works** — 3-step quick-start: Install → Configure (`heron.toml` code block, Shiki-highlighted) → Run (`heron push --dry-run`, terminal output block). Not prose — two code blocks and three numbered labels.
4. **Stats bar** — Three numbers inline: total uploads processed (fictional, plausible), GitHub stars, contributors count. Spans full width. Simple typographic treatment.
5. **Used by** — 4–6 fictional but plausible company/project name pills (not logos — no SVG licensing complexity). Optional section; operator can delete it. Signals traction.
6. **Contributors** — `<img src="https://contrib.rocks/image?repo=heron-cli/heron">` as primary. Static fallback: a small CSS avatar grid of 6 placeholder circles with initials, shown if the img fails to load (CSS `onerror` pattern or a `<picture>`-adjacent approach). Short line: "X contributors on GitHub."
7. **CTA band** — Two prominent buttons: "Read the Docs →" and "Star on GitHub ★". Dark or accent-colored full-width band. Final push before footer.
8. **Footer** — Project name + tagline + MIT license badge + links (GitHub, Docs, Changelog, npm/pkg registry). Copyright line with fictional maintainer handle.

**Explicitly NOT building:**
- Embedded sandbox/playground (iframe, StackBlitz, CodeSandbox) — heavy, breaks static budget, requires server for execution.
- Live Discord chat widget (Crisp, Discord embed) — third-party script, tanks Lighthouse, inappropriate for a small OSS project that hasn't confirmed Discord server.
- Live download counters via API — npm-stat, pkg.go.dev APIs require client-side fetch or SSR; we commit a static number and explain in README how to update it at build time.
- Code of conduct / governance section — belongs in the repo, not the marketing page.
- Sponsors section — legitimate but adds complexity. Operator can add it; we document the pattern in a comment block.

---

## Design conventions

- **Typography:** **Outfit** (Google Fonts, variable, geometric sans, designed for product/tech positioning) as the display and UI typeface. **Geist Mono** (Vercel, free, MIT) exclusively for code blocks, install snippets, and terminal output. Rationale: Outfit is unused in Days 1–9; it reads "friendly and modern" without the startup blandness of Inter. Geist Mono pairs cleanly with it and signals developer credibility. IBM Plex Mono (Day 6) and JetBrains Mono (Day 1) are already taken.
- **Color palette tendency:** **Dark-default with saturated teal accent.** Base: `#0D1117` (GitHub-register near-black — the color developers already associate with terminal/code). Surface cards: `#161B22`. Accent: `#14B8A6` (Tailwind teal-500) — distinct from cobalt `#2563EB` (Day 6), forest green `#1C4A2E` (Day 5), amber (Day 1), lime (Day 3). Teal reads as "modern OSS tooling" — close to the Bun/Vite register without copying either. Secondary text: `#8B949E` (GitHub muted gray). Borders: `#30363D`.
- **Imagery style:** Terminal/code screenshots rendered as static SVG compositions — not real screenshots, but hand-crafted SVG "terminal windows" with fake output. No photography. No Unsplash. Background: a subtle grid-dot pattern in CSS (`radial-gradient` on `#0D1117`). This is the canonical OSS landing page texture without resorting to particle.js.
- **Density:** Sparse-to-moderate. Hero and stats bar are sparse and high-impact. Features grid is moderate (3-col, tight cards). How it works is dense by necessity (code blocks). Contributors is a single image element. No sidebars. Max container ~1100px.

---

## Trust signals to include

- GitHub star count: static text ("★ 2.1k") + shields.io live SVG (`https://img.shields.io/github/stars/heron-cli/heron?style=flat-square`) — two signals, layout doesn't depend on either.
- MIT license badge — shields.io static badge committed as an img tag. Developers scan for this.
- Version badge — `v0.9.1` inline in hero sub-line. Signals active development, not abandoned.
- "X contributors" line above the contrib.rocks image.
- Fictional but plausible "Used by" names — not logos, not links. Just names: "Basalt CI", "Stackform", "Riverline". Enough to signal real-world adoption.
- Changelog link in footer — even pointing to GitHub CHANGELOG.md signals that someone maintains this.

---

## SEO / schema.org

- **Type:** `SoftwareSourceCode` (subtype of `CreativeWork`) + `SoftwareApplication` as a second block. Justification: `SoftwareSourceCode` accurately describes the artifact (the repo, the source); `SoftwareApplication` captures the CLI tool aspect and is what Google actually uses for rich results (download, version, operating system). Both are lightweight JSON-LD objects.
- **Required properties (SoftwareSourceCode):** `name`, `description`, `url` (landing page), `codeRepository` (GitHub URL), `programmingLanguage`, `license`, `version`.
- **Required properties (SoftwareApplication):** `name`, `operatingSystem` (macOS, Linux, Windows), `applicationCategory` ("DeveloperApplication"), `offers` (`price: "0"`, `priceCurrency: "USD"`), `softwareVersion`.
- **Suggested OG image direction:** Dark `#0D1117` background, project name in Outfit Bold at ~72px, teal accent tagline below, faint dot-grid texture, MIT + version badges bottom-left. Static committed PNG (`og-default.png`). One size fits all pages since this is a single-page site.

---

## Static-only fit

No blocking concerns. Every expected live-data feature has a confirmed static substitute:

- **GitHub stars:** shields.io SVG badge (runs at user's browser request, not at build). Static fallback number hardcoded in markup. No build-time API call, no token required.
- **Contributors grid:** `contrib.rocks` single `<img>` tag. Autoupdates without rebuilds. Zero build-time dependency.
- **Install tabs:** Pure HTML + minimal vanilla JS (no framework). Tab state is `aria-selected` toggling. Works without JS (first tab visible by default).
- **Copy-to-clipboard:** `navigator.clipboard.writeText` in a ~10-line vanilla script. Graceful degradation: button visually present, no-JS users can copy manually.
- **Code blocks:** Astro's built-in `<Code>` component using Shiki at build time. Zero client-side syntax highlighting. Pick theme `github-dark` — matches `#0D1117` base.
- **Download counters:** Static numbers committed to a `src/data/stats.json` file. Documented in README: "Run `npm run update-stats` to refresh from pkg.go.dev API before deploy." Build-time fetch, not runtime.

---

## Differentiation — what we'll do better

1. **Tabbed install snippet with copy-to-clipboard:** No free Astro template ships a proper `brew / go install / curl` tab component with clipboard button. This is the single most-used feature on OSS landing pages and is absent everywhere in the free template space.
2. **Shiki-highlighted terminal code blocks:** Actual syntax highlighting at build time using Astro's native `<Code>` component. Generic templates use `<pre><code>` with no highlighting. Developers notice immediately.
3. **Two-layer star count (static + live badge):** Layout never breaks if shields.io is slow. Static number is always readable. Live badge updates automatically. No template in the surveyed set handles both.
4. **contrib.rocks contributors widget + static fallback:** Single `<img>` auto-syncs with the real GitHub repo. Operator sets their repo slug once. Beats manually maintaining an avatar grid in every comparable template.
5. **`SoftwareSourceCode` + `SoftwareApplication` JSON-LD:** No Astro OSS template in the surveyed set ships schema.org markup at all. This gives search engines structured data for rich results (version, OS compatibility, license).
6. **Outfit + Geist Mono pairing — unused in any Day 1–9 template:** Immediately differentiates visually. Outfit's geometric friendliness against Geist Mono's developer credibility is the right register for a well-maintained OSS tool that isn't enterprise-formal.
7. **`#0D1117` GitHub-register dark base:** Developers already live in this color. It reads as "this project is serious" without being alienating. Not a generic `#000` or a trendy near-black with blue tint.
8. **GH Pages one-click deploy, MIT, no CMS dependency:** The typical OSS maintainer has a GitHub account and nothing else. This template deploys from a push to `main` with zero additional accounts required — beating Vercel-first or Netlify-first templates that require additional account wiring.
