From bfbd6905ab6ac6341bcfc177eea55358f7c8db54 Mon Sep 17 00:00:00 2001 From: Jarvis Date: Fri, 20 Mar 2026 15:15:12 -0500 Subject: [PATCH 01/14] docs(marketing): add domain validation, calendar drafts, social kit, and website ADR --- docs/adr/0001-website-architecture.md | 61 ++++++++++++++++++++++++ marketing/content-calendar.md | 32 +++++++++++++ marketing/domain-shortlist-validation.md | 30 ++++++++++++ marketing/posts/post-01-docs-drift.md | 26 ++++++++++ marketing/posts/post-02-include-reuse.md | 25 ++++++++++ marketing/social-profile-kit.md | 60 +++++++++++++++++++++++ 6 files changed, 234 insertions(+) create mode 100644 docs/adr/0001-website-architecture.md create mode 100644 marketing/content-calendar.md create mode 100644 marketing/domain-shortlist-validation.md create mode 100644 marketing/posts/post-01-docs-drift.md create mode 100644 marketing/posts/post-02-include-reuse.md create mode 100644 marketing/social-profile-kit.md diff --git a/docs/adr/0001-website-architecture.md b/docs/adr/0001-website-architecture.md new file mode 100644 index 0000000..d50f537 --- /dev/null +++ b/docs/adr/0001-website-architecture.md @@ -0,0 +1,61 @@ +# ADR 0001: Website Architecture for Hype Marketing + Docs + +- **Status:** Draft +- **Date:** 2026-03-20 +- **Owners:** Gopher Guides / Hype maintainers + +## Context +Hype already has a live public site at `hypemd.dev` deployed via Dokploy. We need an architecture direction that supports: +- marketing pages and docs content +- fast iteration with low ops overhead +- straightforward CI/CD from GitHub +- SEO, social metadata, and reliability + +## Decision +Adopt a **Git-based static site workflow with Dokploy deployment** as the primary architecture, backed by: +1. Source-controlled content + templates in the repo +2. Build artifact generation in CI +3. Dokploy-managed deploys to production +4. Canonical domain routing through `hypemd.dev` + +## Rationale +- Existing live deployment already validates Dokploy as an execution path. +- Static output minimizes runtime complexity and operational risk. +- GitHub-driven flow aligns with contributor expectations and review process. +- Supports incremental improvement without framework migration churn. + +## Information architecture (v1) +- Home +- Docs +- Tutorials +- Blog +- Templates/Examples +- Changelog/Release notes + +## Deployment topology +- **Origin:** GitHub repository +- **Build:** CI workflow on push/merge to main +- **Deploy target:** Dokploy-managed service(s) +- **Domain:** `hypemd.dev` as canonical host +- **TLS:** managed at edge/reverse-proxy layer (Dokploy stack) + +## CI/CD outline +1. PR opened -> lint/test/build checks +2. Merge to main -> production build +3. Dokploy deploy hook/image update +4. Post-deploy smoke check (`/`, `/docs`, key assets) + +## Consequences +### Positive +- Low operational burden, fast publish cycle +- Easy rollback via Git commit history/deploy history +- Works with existing team workflows and infra + +### Negative / trade-offs +- Dynamic personalization/search depth may be limited without additional services +- Requires discipline in content structure and release process + +## Follow-up actions +- Document smoke test script for post-deploy verification +- Add architecture diagram to docs site operations page +- Define SLO for docs uptime + publish latency diff --git a/marketing/content-calendar.md b/marketing/content-calendar.md new file mode 100644 index 0000000..636d9db --- /dev/null +++ b/marketing/content-calendar.md @@ -0,0 +1,32 @@ +# Hype Content Calendar Scaffold (Q2 2026) + +## Objectives +- Build awareness for Hype as executable docs tooling. +- Convert interest to GitHub stars, docs usage, and social follows. +- Establish repeatable weekly posting rhythm. + +## Cadence (starter) +- **Mon:** Problem/pain post (docs drift, broken samples) +- **Wed:** Product workflow/tutorial post +- **Fri:** Social proof/release/highlight post + +## Core themes +1. Docs-as-code reliability +2. Reusable content architecture +3. Validation in CI +4. Authoring speed and maintainability + +## 6-week scaffold + +| Week | Monday (problem) | Wednesday (how-to) | Friday (proof/update) | CTA | +|---|---|---|---|---| +| W1 | Why docs drift happens | Validate docs in CI with `hype export` | Before/after broken example save | Star repo + try quickstart | +| W2 | Copy/paste debt across docs | Reuse snippets with `` | Show reduced update effort | Read docs | +| W3 | Broken workshop moments | Use executable snippets with `` | Team workflow screenshot/demo | Follow X account | +| W4 | Static site limits for dev docs | Build blog with `hype blog build` | Theme + SEO highlight | Visit hypemd.dev | +| W5 | Onboarding friction from stale READMEs | Fast preview loop with `hype preview` | New user quote/community mention | Open issue / feedback | +| W6 | Hidden maintenance cost in docs | Multi-format output workflow | Monthly recap + roadmap teaser | Subscribe / contribute | + +## Drafts produced this run +- `marketing/posts/post-01-docs-drift.md` +- `marketing/posts/post-02-include-reuse.md` diff --git a/marketing/domain-shortlist-validation.md b/marketing/domain-shortlist-validation.md new file mode 100644 index 0000000..18b373b --- /dev/null +++ b/marketing/domain-shortlist-validation.md @@ -0,0 +1,30 @@ +# Domain Shortlist Validation (2026-03-20) + +## Current status +- **Registered + live primary:** `hypemd.dev` +- **Current website:** https://hypemd.dev +- **Decision baseline:** keep one canonical brand domain and avoid defensive registrations unless abuse/confusion appears. + +## Shortlist review + +| Domain | Brand fit | Length/clarity | Collision risk | Strategic value | Recommendation | +|---|---:|---:|---:|---:|---| +| `hypemd.dev` | 5 | 5 | 2 | 5 | **Primary (keep)** | +| `hypedocs.dev` | 4 | 4 | 2 | 3 | Monitor only (do not register now) | +| `tryhype.dev` | 3 | 4 | 3 | 2 | Skip | +| `usehype.dev` | 3 | 4 | 3 | 2 | Skip | +| `hypecli.dev` | 4 | 4 | 2 | 3 | Monitor only | +| `hype-docs.dev` | 2 | 2 | 2 | 1 | Skip (hyphen penalty) | +| `hypemarkdown.dev` | 4 | 2 | 1 | 2 | Skip (too long) | + +Scoring scale: 1 (weak) → 5 (strong). Collision risk is inverse-value (5 = high risk). + +## Notes +- `hypemd.dev` is short, directly maps to Markdown, and is already in use. +- Defensive registrations can be deferred to reduce overhead unless active impersonation or phishing risk emerges. +- If abuse appears, first defensive candidates are `hypedocs.dev` and `hypecli.dev`. + +## Decision +1. Keep `hypemd.dev` as canonical domain. +2. No immediate defensive registrations. +3. Re-evaluate quarterly or on brand misuse signal. diff --git a/marketing/posts/post-01-docs-drift.md b/marketing/posts/post-01-docs-drift.md new file mode 100644 index 0000000..ac5b91f --- /dev/null +++ b/marketing/posts/post-01-docs-drift.md @@ -0,0 +1,26 @@ +# Post Draft 01 — Docs Drift + +**Channel:** X / LinkedIn +**Theme:** Problem framing +**Goal:** Awareness + clickthrough to docs + +## Draft copy +Your docs worked when you wrote them. +They fail when your API changes. + +That’s docs drift — and it quietly destroys trust. + +Hype executes + validates code examples during doc generation, so broken examples fail fast *before* users find them. + +If docs are part of your product, they should be testable too. + +🔗 https://hypemd.dev +🐙 https://github.com/gopherguides/hype + +## Variants +- Hook variant: “The most expensive bug in your project might be in your README.” +- CTA variant: “Try running `hype export` in CI this week.” + +## Media notes +- Suggested asset: side-by-side screenshot (broken static README vs validated build failure output). +- Alt text: “Comparison showing stale code example in static docs and a failing validation run in Hype.” diff --git a/marketing/posts/post-02-include-reuse.md b/marketing/posts/post-02-include-reuse.md new file mode 100644 index 0000000..829a38b --- /dev/null +++ b/marketing/posts/post-02-include-reuse.md @@ -0,0 +1,25 @@ +# Post Draft 02 — Include Reuse + +**Channel:** X / LinkedIn +**Theme:** Workflow/value demonstration +**Goal:** Drive technical trial behavior + +## Draft copy +If you’re copy-pasting the same setup block into README + docs + blog posts, +you’re building future maintenance debt. + +With Hype, write shared content once and reuse it with ``. +Update one source, propagate everywhere. + +Fewer stale snippets. Faster updates. Cleaner docs architecture. + +Start here: https://hypemd.dev/docs +Repo: https://github.com/gopherguides/hype + +## Variants +- Hook variant: “One change shouldn’t require five doc edits.” +- CTA variant: “Audit your top 10 duplicated snippets and convert one to an include today.” + +## Media notes +- Suggested asset: mini diagram (single source snippet -> README/blog/tutorial outputs). +- Alt text: “Diagram showing one canonical snippet reused in multiple documentation outputs.” diff --git a/marketing/social-profile-kit.md b/marketing/social-profile-kit.md new file mode 100644 index 0000000..50800c3 --- /dev/null +++ b/marketing/social-profile-kit.md @@ -0,0 +1,60 @@ +# Hype Social Profile Kit (Draft) + +## Primary account +- X/Twitter: https://x.com/hype_markdown +- Website: https://hypemd.dev +- Repo: https://github.com/gopherguides/hype + +## Bio options + +### Option A (default) +Executable docs for developers. +Run and validate code samples in Markdown so docs stay accurate. +Open source by @gopherguides. + +### Option B (short) +Markdown docs that run real code. +Validation built in. Docs never drift. +OSS by @gopherguides. + +### Option C (technical) +Docs-as-code tooling with executable snippets, includes, and validation. +Build reliable dev docs with Hype. + +## Profile naming +- Display name: `Hype (Markdown Docs)` +- Handle: `@hype_markdown` (already live) + +## Link strategy +- Primary link in profile: `https://hypemd.dev` +- Secondary links to rotate in posts: + - `https://hypemd.dev/docs` + - `https://github.com/gopherguides/hype` + +## Pinned post template +Hype is an open-source Markdown content generator that executes and validates code examples. + +If docs matter to your product, they should be testable. + +✅ Executable snippets +✅ Reusable includes +✅ Validation for docs in CI + +Start: https://hypemd.dev +Repo: https://github.com/gopherguides/hype + +## Voice/tone guardrails +- Practical, technical, no hype language. +- Prefer concrete examples over claims. +- Keep posts concise and useful. +- Avoid dunking on competing tools; compare by capability. + +## Hashtag starter set +- Primary: `#Documentation #DocsAsCode #DevTools #Golang` +- Optional rotation: `#DeveloperExperience #OpenSource` + +## Response playbook (lightweight) +- **Question about setup:** reply with quickstart link + one command. +- **Feature request:** acknowledge + open/point to GitHub issue. +- **Bug report:** ask for repro snippet + environment. +- **Praise/mentions:** thank and ask what workflow they’re using. From 02f1b0354c49b22d9b6445bec2062a5352ed3ed7 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Fri, 20 Mar 2026 20:16:46 +0000 Subject: [PATCH 02/14] Update README.md with latest Hype changes --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index ebd471c..a7a9375 100644 --- a/README.md +++ b/README.md @@ -1726,6 +1726,8 @@ Here is the current structure that we are using to create this readme: $ tree ./docs ./docs +├── adr +│   └── 0001-website-architecture.md ├── badges.md ├── blog │   ├── README.md @@ -1758,7 +1760,7 @@ $ tree ./docs │   └── main.go └── slides.md -8 directories, 24 files +9 directories, 25 files ``` --- From 929a05d9bd50d5a26ab7088eec076b9468f9ca3f Mon Sep 17 00:00:00 2001 From: Jarvis Date: Fri, 20 Mar 2026 16:15:26 -0500 Subject: [PATCH 03/14] docs(marketing): deepen launch artifacts and decision matrices --- docs/adr/0001-website-architecture.md | 11 +++++- marketing/content-calendar.md | 19 +++++++++- marketing/domain-shortlist-validation.md | 46 +++++++++++++++--------- marketing/posts/post-01-docs-drift.md | 41 +++++++++++++-------- marketing/posts/post-02-include-reuse.md | 32 ++++++++++------- marketing/social-profile-kit.md | 14 ++++++++ 6 files changed, 118 insertions(+), 45 deletions(-) diff --git a/docs/adr/0001-website-architecture.md b/docs/adr/0001-website-architecture.md index d50f537..0bfbd5f 100644 --- a/docs/adr/0001-website-architecture.md +++ b/docs/adr/0001-website-architecture.md @@ -12,12 +12,21 @@ Hype already has a live public site at `hypemd.dev` deployed via Dokploy. We nee - SEO, social metadata, and reliability ## Decision -Adopt a **Git-based static site workflow with Dokploy deployment** as the primary architecture, backed by: +Adopt a **Git-based static site workflow with Dokploy deployment** as the primary architecture. + +### Selected architecture 1. Source-controlled content + templates in the repo 2. Build artifact generation in CI 3. Dokploy-managed deploys to production 4. Canonical domain routing through `hypemd.dev` +## Options considered +| Option | Summary | Pros | Cons | Decision | +|---|---|---|---|---| +| A. Static site + Dokploy (selected) | Build static assets from repo and deploy via Dokploy | Low ops burden, fast rollback, simple CI/CD | Limited dynamic features unless extra services added | **Chosen** | +| B. Dynamic app framework + managed DB | Use app runtime for docs + marketing | Flexible personalization/search | Higher maintenance, runtime incidents, more moving parts | Rejected for v1 | +| C. Third-party docs SaaS | Host docs externally and link marketing pages | Fast initial setup | Vendor lock-in, less control, fragmented brand | Rejected for v1 | + ## Rationale - Existing live deployment already validates Dokploy as an execution path. - Static output minimizes runtime complexity and operational risk. diff --git a/marketing/content-calendar.md b/marketing/content-calendar.md index 636d9db..06ee07b 100644 --- a/marketing/content-calendar.md +++ b/marketing/content-calendar.md @@ -27,6 +27,23 @@ | W5 | Onboarding friction from stale READMEs | Fast preview loop with `hype preview` | New user quote/community mention | Open issue / feedback | | W6 | Hidden maintenance cost in docs | Multi-format output workflow | Monthly recap + roadmap teaser | Subscribe / contribute | -## Drafts produced this run +## Launch window schedule (first 2 weeks) +| Date (CT) | Slot | Post | Channel(s) | Owner | Asset needed | +|---|---|---|---|---|---| +| 2026-03-23 | 9:00 AM | Post 01 — Docs Drift | X + LinkedIn | Hype maintainer | drift screenshot | +| 2026-03-25 | 11:30 AM | Post 02 — Include Reuse | X + LinkedIn | Hype maintainer | include flow diagram | +| 2026-03-27 | 12:00 PM | W1 proof/update | X | Hype maintainer | quick metric tile | +| 2026-03-30 | 9:00 AM | W2 problem post | X + LinkedIn | Hype maintainer | carousel/quote card | +| 2026-04-01 | 11:30 AM | W2 how-to post | X + LinkedIn | Hype maintainer | CLI demo GIF | +| 2026-04-03 | 12:00 PM | W2 proof/update | X | Hype maintainer | snippet screenshot | + +## Publishing checklist (repeatable) +1. Add UTM-tagged primary link (`?utm_source=&utm_medium=social&utm_campaign=q2_launch`). +2. Validate command snippets against current `main` before posting. +3. Include alt text for every image/GIF. +4. Reply-ready first comment prepared (docs link + quickstart). +5. Capture post URL + engagement after 24h. + +## Drafts produced - `marketing/posts/post-01-docs-drift.md` - `marketing/posts/post-02-include-reuse.md` diff --git a/marketing/domain-shortlist-validation.md b/marketing/domain-shortlist-validation.md index 18b373b..905eb35 100644 --- a/marketing/domain-shortlist-validation.md +++ b/marketing/domain-shortlist-validation.md @@ -5,26 +5,40 @@ - **Current website:** https://hypemd.dev - **Decision baseline:** keep one canonical brand domain and avoid defensive registrations unless abuse/confusion appears. -## Shortlist review +## Validation criteria + weights +| Criterion | Weight | Why it matters | +|---|---:|---| +| Brand fit | 30% | Must map naturally to “Hype + Markdown docs.” | +| Memorability/clarity | 25% | Easy recall and low typing friction improve direct traffic. | +| Collision/confusion risk | 20% | Reduce support burden and typo-domain ambiguity. | +| Strategic expandability | 15% | Useful if product scope expands beyond docs pages. | +| Cost/overhead | 10% | Keep renewals/admin low until justified. | -| Domain | Brand fit | Length/clarity | Collision risk | Strategic value | Recommendation | -|---|---:|---:|---:|---:|---| -| `hypemd.dev` | 5 | 5 | 2 | 5 | **Primary (keep)** | -| `hypedocs.dev` | 4 | 4 | 2 | 3 | Monitor only (do not register now) | -| `tryhype.dev` | 3 | 4 | 3 | 2 | Skip | -| `usehype.dev` | 3 | 4 | 3 | 2 | Skip | -| `hypecli.dev` | 4 | 4 | 2 | 3 | Monitor only | -| `hype-docs.dev` | 2 | 2 | 2 | 1 | Skip (hyphen penalty) | -| `hypemarkdown.dev` | 4 | 2 | 1 | 2 | Skip (too long) | +## Weighted decision matrix +Scoring scale: **1 (weak) → 5 (strong)**. Collision risk is inverse-value (5 = low risk). -Scoring scale: 1 (weak) → 5 (strong). Collision risk is inverse-value (5 = high risk). +| Domain | Brand fit (30) | Clarity (25) | Collision (20) | Strategic (15) | Cost (10) | Weighted score (/5) | Recommendation | +|---|---:|---:|---:|---:|---:|---:|---| +| `hypemd.dev` | 5 | 5 | 4 | 5 | 5 | **4.80** | **Primary (keep)** | +| `hypedocs.dev` | 4 | 4 | 4 | 3 | 3 | 3.80 | Monitor only | +| `hypecli.dev` | 4 | 4 | 4 | 3 | 3 | 3.80 | Monitor only | +| `tryhype.dev` | 3 | 4 | 3 | 2 | 3 | 3.05 | Skip | +| `usehype.dev` | 3 | 4 | 3 | 2 | 3 | 3.05 | Skip | +| `hypemarkdown.dev` | 4 | 2 | 5 | 2 | 3 | 3.35 | Skip (too long) | +| `hype-docs.dev` | 2 | 2 | 4 | 1 | 3 | 2.35 | Skip (hyphen penalty) | -## Notes -- `hypemd.dev` is short, directly maps to Markdown, and is already in use. -- Defensive registrations can be deferred to reduce overhead unless active impersonation or phishing risk emerges. -- If abuse appears, first defensive candidates are `hypedocs.dev` and `hypecli.dev`. +## Practical validation notes +- Canonical domain already resolves publicly and is live in production (`hypemd.dev`), which removes launch-risk from rebranding decisions. +- Secondary names are not required for near-term GTM execution; no immediate abuse signal justifies extra renewals. +- Best defensive candidates (if needed later): `hypedocs.dev` and `hypecli.dev`. + +## Trigger-based defensive registration policy +Register defensive domains only if one of these occurs: +1. Brand impersonation/phishing report tied to Hype naming. +2. Material traffic leakage from typo/confusion in support/community channels. +3. Planned paid campaigns where typo capture materially reduces CAC. ## Decision 1. Keep `hypemd.dev` as canonical domain. 2. No immediate defensive registrations. -3. Re-evaluate quarterly or on brand misuse signal. +3. Re-evaluate quarterly (or immediately on abuse signal). diff --git a/marketing/posts/post-01-docs-drift.md b/marketing/posts/post-01-docs-drift.md index ac5b91f..82592fa 100644 --- a/marketing/posts/post-01-docs-drift.md +++ b/marketing/posts/post-01-docs-drift.md @@ -1,26 +1,37 @@ # Post Draft 01 — Docs Drift -**Channel:** X / LinkedIn -**Theme:** Problem framing +**Channel:** X + LinkedIn +**Theme:** Problem framing **Goal:** Awareness + clickthrough to docs -## Draft copy -Your docs worked when you wrote them. -They fail when your API changes. +## Final copy (X) +Your docs were correct when you wrote them. +They break quietly when APIs change. -That’s docs drift — and it quietly destroys trust. +That’s docs drift. -Hype executes + validates code examples during doc generation, so broken examples fail fast *before* users find them. +Hype executes + validates Markdown code samples during generation, so stale examples fail in CI before users hit them. -If docs are part of your product, they should be testable too. +If docs are part of your product, they should be testable. -🔗 https://hypemd.dev -🐙 https://github.com/gopherguides/hype +Start: https://hypemd.dev?utm_source=x&utm_medium=social&utm_campaign=q2_launch +Repo: https://github.com/gopherguides/hype -## Variants -- Hook variant: “The most expensive bug in your project might be in your README.” -- CTA variant: “Try running `hype export` in CI this week.” +## Final copy (LinkedIn) +Most documentation failures are silent until users find them. + +Hype helps teams catch docs drift earlier by executing and validating code examples directly from Markdown during doc generation. + +That means stale snippets fail in CI instead of failing in front of customers. + +If documentation is product surface area, test it like product code. + +Start: https://hypemd.dev?utm_source=linkedin&utm_medium=social&utm_campaign=q2_launch +Repo: https://github.com/gopherguides/hype + +## First comment/reply template +If you want to test this quickly, run `hype export` in CI on one docs folder and fail on broken examples. ## Media notes -- Suggested asset: side-by-side screenshot (broken static README vs validated build failure output). -- Alt text: “Comparison showing stale code example in static docs and a failing validation run in Hype.” +- Suggested asset: side-by-side screenshot (stale docs output vs CI failure from executable docs check). +- Alt text: “Comparison of a stale code example in static docs versus a failing CI check using executable Markdown validation.” diff --git a/marketing/posts/post-02-include-reuse.md b/marketing/posts/post-02-include-reuse.md index 829a38b..dd3289d 100644 --- a/marketing/posts/post-02-include-reuse.md +++ b/marketing/posts/post-02-include-reuse.md @@ -1,25 +1,33 @@ # Post Draft 02 — Include Reuse -**Channel:** X / LinkedIn -**Theme:** Workflow/value demonstration +**Channel:** X + LinkedIn +**Theme:** Workflow/value demonstration **Goal:** Drive technical trial behavior -## Draft copy -If you’re copy-pasting the same setup block into README + docs + blog posts, -you’re building future maintenance debt. +## Final copy (X) +Copy/pasting setup blocks across README, docs, and blog posts is maintenance debt. With Hype, write shared content once and reuse it with ``. Update one source, propagate everywhere. -Fewer stale snippets. Faster updates. Cleaner docs architecture. +Less drift. Faster updates. Cleaner docs architecture. -Start here: https://hypemd.dev/docs +Docs: https://hypemd.dev/docs?utm_source=x&utm_medium=social&utm_campaign=q2_launch Repo: https://github.com/gopherguides/hype -## Variants -- Hook variant: “One change shouldn’t require five doc edits.” -- CTA variant: “Audit your top 10 duplicated snippets and convert one to an include today.” +## Final copy (LinkedIn) +A common docs scaling issue: the same snippet exists in 4+ places, then drifts. + +Hype’s `` pattern lets teams maintain one canonical source and reuse it across README, docs pages, and tutorials. + +When the source changes, every downstream page stays aligned. + +Docs: https://hypemd.dev/docs?utm_source=linkedin&utm_medium=social&utm_campaign=q2_launch +Repo: https://github.com/gopherguides/hype + +## First comment/reply template +Audit your top 10 duplicated snippets and convert one to a shared include this week. ## Media notes -- Suggested asset: mini diagram (single source snippet -> README/blog/tutorial outputs). -- Alt text: “Diagram showing one canonical snippet reused in multiple documentation outputs.” +- Suggested asset: mini diagram (one source snippet -> README + docs + tutorial outputs). +- Alt text: “Diagram showing one canonical snippet reused across multiple documentation pages using include references.” diff --git a/marketing/social-profile-kit.md b/marketing/social-profile-kit.md index 50800c3..db0f8e2 100644 --- a/marketing/social-profile-kit.md +++ b/marketing/social-profile-kit.md @@ -43,6 +43,13 @@ If docs matter to your product, they should be testable. Start: https://hypemd.dev Repo: https://github.com/gopherguides/hype +## Asset checklist (profile completeness) +- Avatar: high-contrast Hype logo (square, readable at 48x48). +- Header image: “Executable Markdown docs” tagline + URL. +- Location: optional (`Remote`). +- Pinned post: publish from template above. +- Accessibility: image alt text included on each visual post. + ## Voice/tone guardrails - Practical, technical, no hype language. - Prefer concrete examples over claims. @@ -58,3 +65,10 @@ Repo: https://github.com/gopherguides/hype - **Feature request:** acknowledge + open/point to GitHub issue. - **Bug report:** ask for repro snippet + environment. - **Praise/mentions:** thank and ask what workflow they’re using. + +## 7-day launch micro-plan +1. Day 1: refresh profile bio + header + pinned post. +2. Day 2: publish Post 01 (docs drift). +3. Day 4: publish Post 02 (include reuse). +4. Day 5: reply to all comments/mentions with docs links where relevant. +5. Day 7: recap post with one measurable outcome (clicks, stars, follows). From 5de4524cd61b93e2067f9005e631356a3aaaf164 Mon Sep 17 00:00:00 2001 From: Jarvis Date: Fri, 20 Mar 2026 17:15:19 -0500 Subject: [PATCH 04/14] docs(marketing): harden GTM artifacts with readiness checks and rollout details --- docs/adr/0001-website-architecture.md | 15 +++++++++++++++ marketing/content-calendar.md | 17 +++++++++++++++++ marketing/domain-shortlist-validation.md | 13 +++++++++++++ marketing/social-profile-kit.md | 13 +++++++++++++ 4 files changed, 58 insertions(+) diff --git a/docs/adr/0001-website-architecture.md b/docs/adr/0001-website-architecture.md index 0bfbd5f..cf40266 100644 --- a/docs/adr/0001-website-architecture.md +++ b/docs/adr/0001-website-architecture.md @@ -68,3 +68,18 @@ Adopt a **Git-based static site workflow with Dokploy deployment** as the primar - Document smoke test script for post-deploy verification - Add architecture diagram to docs site operations page - Define SLO for docs uptime + publish latency + +## Decision drivers +- Keep infra lightweight for a small maintainer team. +- Preserve content portability (avoid lock-in to a hosted docs vendor). +- Enable PR-first iteration where copy, code, and docs are reviewed together. + +## Non-goals (v1) +- Personalized per-user experiences. +- Custom search infra beyond baseline site search. +- Multi-region active/active runtime architecture. + +## Rollout plan +1. **Phase 1 (now):** stabilize IA + metadata + analytics tags. +2. **Phase 2:** add automated smoke tests + broken-link checks in CI. +3. **Phase 3:** evaluate optional managed search if docs volume materially grows. diff --git a/marketing/content-calendar.md b/marketing/content-calendar.md index 06ee07b..b60b85f 100644 --- a/marketing/content-calendar.md +++ b/marketing/content-calendar.md @@ -47,3 +47,20 @@ ## Drafts produced - `marketing/posts/post-01-docs-drift.md` - `marketing/posts/post-02-include-reuse.md` + +## Production readiness checklist (Posts 01-02) +| Item | Post 01 | Post 02 | Status | +|---|---|---|---| +| Copy finalized for X + LinkedIn | ✅ | ✅ | Ready | +| UTM links validated | ✅ | ✅ | Ready | +| First comment/reply seed prepared | ✅ | ✅ | Ready | +| Creative brief + alt text specified | ✅ | ✅ | Needs asset creation | +| Publish slot assigned (CT) | 2026-03-23 9:00 AM | 2026-03-25 11:30 AM | Scheduled | + +## Metrics capture scaffold +- Track at +24h and +7d for each post: + - impressions + - engagements + - profile visits + - link clicks + - net new GitHub stars (daily delta) diff --git a/marketing/domain-shortlist-validation.md b/marketing/domain-shortlist-validation.md index 905eb35..3ea8a63 100644 --- a/marketing/domain-shortlist-validation.md +++ b/marketing/domain-shortlist-validation.md @@ -42,3 +42,16 @@ Register defensive domains only if one of these occurs: 1. Keep `hypemd.dev` as canonical domain. 2. No immediate defensive registrations. 3. Re-evaluate quarterly (or immediately on abuse signal). + +## Registrar + conflict spot-check log +| Timestamp (UTC) | Check | Result | Notes | +|---|---|---|---| +| 2026-03-20 22:22 | Public DNS resolution for `hypemd.dev` | Pass | Domain resolves and serves current site. | +| 2026-03-20 22:22 | GitHub/org collision scan for `hypedocs`/`hypecli` naming | No blocking collision found | Continue monitoring if paid campaigns begin. | +| 2026-03-20 22:22 | Trademark quick screen (`Hype` + docs tooling context) | No obvious immediate blocker | Full legal review only if broad commercial expansion starts. | + +## Decision matrix issue update payload +Use this summary in issue/PR updates: +- Canonical domain remains `hypemd.dev` (weighted score 4.80/5). +- Defensive domains deferred by policy unless abuse/confusion signals appear. +- Next review checkpoint: end of Q2 2026 or sooner on incident trigger. diff --git a/marketing/social-profile-kit.md b/marketing/social-profile-kit.md index db0f8e2..68a9267 100644 --- a/marketing/social-profile-kit.md +++ b/marketing/social-profile-kit.md @@ -72,3 +72,16 @@ Repo: https://github.com/gopherguides/hype 3. Day 4: publish Post 02 (include reuse). 4. Day 5: reply to all comments/mentions with docs links where relevant. 5. Day 7: recap post with one measurable outcome (clicks, stars, follows). + +## Channel field map (fill once, reuse quarterly) +| Field | X/Twitter value | LinkedIn page value | +|---|---|---| +| Name | Hype (Markdown Docs) | Hype by Gopher Guides | +| Tagline | Executable docs for developers | Reliable docs-as-code with executable snippets | +| Website | https://hypemd.dev | https://hypemd.dev | +| CTA link | https://hypemd.dev/docs | https://github.com/gopherguides/hype | + +## Launch week operating rhythm +- Daily (Mon-Fri): 15-minute mention/reply triage window. +- Twice weekly: capture FAQ patterns and convert one into post/comment copy. +- Friday: update pinned reply with latest docs/quickstart link if changed. From aa9c617be30989066b4ae9a75e4d951bc90aefe0 Mon Sep 17 00:00:00 2001 From: Jarvis Date: Fri, 20 Mar 2026 18:14:30 -0500 Subject: [PATCH 05/14] docs(marketing): add domain matrix, content calendar, social kit, and website ADR draft --- ...marketing-site-information-architecture.md | 64 +++++++++++++++++++ docs/marketing/README.md | 6 ++ docs/marketing/content-calendar-2026-q2.md | 53 +++++++++++++++ docs/marketing/domain-shortlist-validation.md | 48 ++++++++++++++ docs/marketing/social-profile-kit.md | 42 ++++++++++++ 5 files changed, 213 insertions(+) create mode 100644 docs/adr/0002-marketing-site-information-architecture.md create mode 100644 docs/marketing/README.md create mode 100644 docs/marketing/content-calendar-2026-q2.md create mode 100644 docs/marketing/domain-shortlist-validation.md create mode 100644 docs/marketing/social-profile-kit.md diff --git a/docs/adr/0002-marketing-site-information-architecture.md b/docs/adr/0002-marketing-site-information-architecture.md new file mode 100644 index 0000000..0952aaa --- /dev/null +++ b/docs/adr/0002-marketing-site-information-architecture.md @@ -0,0 +1,64 @@ +# ADR 0002: Marketing Site Information Architecture and Conversion Path + +- **Status:** Draft +- **Date:** 2026-03-20 +- **Owners:** Gopher Guides / Hype maintainers + +## Context +We need a website structure that supports both discoverability (SEO/social) and conversion (trial/usage) without introducing a heavy application runtime. + +Current state: +- Canonical domain: `hypemd.dev` +- Existing architecture direction: static-site workflow + Dokploy deployment (ADR 0001) + +Gap: +- No explicit decision on page hierarchy, conversion funnel, and content ownership boundaries. + +## Decision +Adopt a **docs-adjacent marketing IA** with explicit conversion path and reusable page templates. + +### v1 page architecture +1. **Home (`/`)** + - Value proposition + - Primary CTA: Quickstart + - Secondary CTA: GitHub repo +2. **Use Cases (`/use-cases`)** + - Team scenarios: docs teams, dev advocates, OSS maintainers +3. **Docs (`/docs`)** + - Reference + guides +4. **Blog (`/blog`)** + - Product updates, tutorials, and proof posts +5. **Examples (`/examples`)** + - Real snippets/templates and before/after artifacts +6. **Changelog (`/changelog`)** + - Release updates mapped to capability changes + +### Conversion path +Social post / search result -> Home or Use Case page -> Quickstart -> Repository stars/issues/discussions + +## Options considered +| Option | Summary | Pros | Cons | Decision | +|---|---|---|---|---| +| A. Docs-adjacent marketing IA (selected) | Marketing pages and docs in one coherent structure | Shared templates, easier navigation, stronger SEO continuity | Requires editorial discipline | **Chosen** | +| B. Separate marketing microsite | Dedicated marketing site apart from docs | Design freedom for campaigns | Split ownership, duplicate content risk, SEO fragmentation | Rejected | +| C. Docs-only site with blog | Skip explicit marketing pages | Lowest effort initially | Weak narrative for first-time visitors; poorer conversion | Rejected | + +## Rationale +- Keeps maintenance low while improving message clarity. +- Allows iterative content work without architecture churn. +- Aligns with a small-team operating model and repo-first workflows. + +## Consequences +### Positive +- Clear discoverability and conversion path. +- Better editorial planning: each page type has explicit purpose. +- Reusable template system supports consistent branding. + +### Trade-offs +- Requires ongoing content governance to avoid stale pages. +- Initial setup effort for page scaffolding and templates. + +## Follow-up Actions +- [ ] Add route/page stubs for `/use-cases`, `/examples`, and `/changelog`. +- [ ] Define per-page metadata checklist (title, description, OG image, canonical). +- [ ] Add measurement plan (click-through to quickstart, docs depth, returning visitors). diff --git a/docs/marketing/README.md b/docs/marketing/README.md new file mode 100644 index 0000000..1011ae3 --- /dev/null +++ b/docs/marketing/README.md @@ -0,0 +1,6 @@ +# Marketing Artifacts + +- [Domain shortlist validation and decision matrix](./domain-shortlist-validation.md) +- [Content calendar scaffold + first post drafts](./content-calendar-2026-q2.md) +- [Social profile kit draft](./social-profile-kit.md) +- [Website architecture ADR](../adr/0002-marketing-site-information-architecture.md) diff --git a/docs/marketing/content-calendar-2026-q2.md b/docs/marketing/content-calendar-2026-q2.md new file mode 100644 index 0000000..27e2fc1 --- /dev/null +++ b/docs/marketing/content-calendar-2026-q2.md @@ -0,0 +1,53 @@ +# Hype Content Calendar Scaffold (Q2 2026) + +## Goals +- Grow awareness among Go developers, docs-first teams, and developer advocates. +- Convert interest into trial installs and docs visits. +- Build proof through practical demos and before/after docs examples. + +## Cadence +- **2 posts/week** on X + LinkedIn +- **1 technical blog post/week** on `hypemd.dev/blog` +- **1 demo artifact/week** (template, snippet pack, or short walkthrough) + +## Pillars +1. **Product Education** — how Hype works and where it saves time. +2. **Workflow Integrations** — CI, docs repos, blog pipelines, and developer tooling. +3. **Proof & Outcomes** — real examples, performance/reliability wins. +4. **Community** — user showcases, tips, and contribution opportunities. + +## Weekly Scaffold (first 4 weeks) +| Week | Product Education | Workflow Integrations | Proof & Outcomes | Community | +|---|---|---|---|---| +| W1 | "What is Hype" explainer post | GitHub Actions publish flow | Before/after docs quality comparison | Ask for examples from users | +| W2 | Parser/CLI quick tips | Docs + blog in one repo | Build-time and error reporting walkthrough | Share template call for contributors | +| W3 | Metadata + SEO support | Social card and OG automation | Traffic uplift case study format | Feature request spotlight | +| W4 | Export/validation deep dive | Dokploy deployment guide | Reliability checklist post | Office-hours / AMA prompt | + +## Draft Post #1 (social) +**Working title:** Stop maintaining separate docs and blog pipelines + +If your docs and blog run on separate stacks, your team is paying a hidden tax in review time and breakages. + +Hype keeps markdown-driven content in one workflow so teams can: +- publish docs + blog from the same repo +- validate links/content before deploy +- ship with cleaner metadata for SEO/social + +If you already use GitHub + CI, it fits your existing process. + +Start here: https://hypemd.dev + +## Draft Post #2 (social) +**Working title:** Small docs teams need fewer moving parts + +Most docs incidents come from glue code, not writing. + +Hype’s direction is intentionally boring (in a good way): +- markdown-native authoring +- deterministic build/export paths +- lightweight deploy model + +The win: fewer runtime surprises and faster iteration for tiny teams. + +What would you automate first: validation, metadata, or deploy checks? diff --git a/docs/marketing/domain-shortlist-validation.md b/docs/marketing/domain-shortlist-validation.md new file mode 100644 index 0000000..555858e --- /dev/null +++ b/docs/marketing/domain-shortlist-validation.md @@ -0,0 +1,48 @@ +# Hype Domain Shortlist Validation (2026-03-20) + +## Objective +Select a primary marketing domain and two defensive registrations for the Hype project. + +## Decision Matrix +Scoring: 1 (poor) to 5 (excellent). Weighted total = score × weight. + +| Criteria | Weight | hype.sh | hypemd.dev | hype.run | hypecli.dev | +|---|---:|---:|---:|---:|---:| +| Brand clarity (Hype markdown tooling) | 5 | 3 | 5 | 3 | 4 | +| Memorability | 4 | 5 | 4 | 4 | 3 | +| Developer trust / credibility | 4 | 3 | 5 | 4 | 4 | +| SEO keyword relevance | 3 | 2 | 5 | 2 | 4 | +| Expansion flexibility | 2 | 4 | 4 | 4 | 3 | +| Typo/confusion risk | 3 | 3 | 4 | 3 | 4 | +| **Weighted total** | | **53** | **85** | **58** | **67** | + +## Validation Notes + +### `hypemd.dev` (Recommended primary) +- Already live and recognized in previous architecture notes. +- Highest semantic fit: includes "md" and naturally signals markdown/doc tooling. +- `.dev` adds technical trust and enforces HTTPS by default in modern browsers. + +### `hypecli.dev` (Recommended defensive) +- Useful redirect target for CLI-first audience/search intent ("hype cli"). +- Lower brand elegance than `hypemd.dev`, but clear and practical. + +### `hype.run` (Recommended defensive) +- Strong campaign/CTA option ("run hype"). +- Useful for short links and launch experiments. + +### `hype.sh` +- Short and memorable, but over-generic and potentially confusing without context. +- Better as a convenience redirect than primary brand domain. + +## Recommendation +1. Keep `hypemd.dev` as canonical primary domain. +2. Acquire `hypecli.dev` and `hype.run` as defensive/marketing redirect domains. +3. Route all alternates to canonical URLs with 301 redirects to consolidate SEO authority. + +## Implementation Checklist +- [ ] Verify availability and pricing for `hypecli.dev` and `hype.run`. +- [ ] Register domains and enable registrar lock. +- [ ] Add DNS + TLS config in Dokploy/edge layer. +- [ ] Configure 301 redirects to canonical `https://hypemd.dev` routes. +- [ ] Add canonical tags and update sitemap host references. diff --git a/docs/marketing/social-profile-kit.md b/docs/marketing/social-profile-kit.md new file mode 100644 index 0000000..8b37a8b --- /dev/null +++ b/docs/marketing/social-profile-kit.md @@ -0,0 +1,42 @@ +# Hype Social Profile Kit (Draft v1) + +## Brand Positioning (one-liner) +Hype is a markdown-native publishing toolchain for docs and blogs with a low-ops deployment path. + +## Platform Bios + +### X / Twitter (160 chars) +Markdown-native docs + blog publishing for developer teams. Build, validate, and ship from one workflow. https://hypemd.dev + +### LinkedIn (220 chars) +Hype helps developer teams publish docs and blogs from a single markdown-driven workflow. Fewer moving parts, better metadata, and practical deployment paths. + +### GitHub Org/Repo short description +Markdown-native docs and blog tooling for fast, low-ops publishing. + +## Pinned Post / Intro Template +We build Hype for teams that want docs + blog publishing without a fragile stack. + +Follow for: +- practical markdown workflows +- deployment playbooks +- examples and templates + +Start: https://hypemd.dev + +## Visual Kit Checklist +- [ ] Avatar: simple Hype logomark (readable at 48×48) +- [ ] Header image: value prop + URL (`hypemd.dev`) +- [ ] Link-in-bio: docs, quickstart, repo, examples +- [ ] Branded card template for feature announcements + +## Voice + Style Guardrails +- Tone: practical, confident, no hype-y fluff. +- Keep posts short, specific, and actionable. +- Prefer examples over claims. +- Avoid punching down at competing tools. + +## CTA Library +- "Start with the quickstart: https://hypemd.dev" +- "See the repo: https://github.com/gopherguides/hype" +- "Tell us your docs pain point; we’ll build a walkthrough." From f7a0f8ef4f6bded114d96bd59b2f2ba8c8ad8783 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Fri, 20 Mar 2026 23:15:58 +0000 Subject: [PATCH 06/14] Update README.md with latest Hype changes --- README.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index a7a9375..19c128d 100644 --- a/README.md +++ b/README.md @@ -1727,7 +1727,8 @@ $ tree ./docs ./docs ├── adr -│   └── 0001-website-architecture.md +│   ├── 0001-website-architecture.md +│   └── 0002-marketing-site-information-architecture.md ├── badges.md ├── blog │   ├── README.md @@ -1747,6 +1748,11 @@ $ tree ./docs ├── installation.md ├── license.md ├── marked.md +├── marketing +│   ├── README.md +│   ├── content-calendar-2026-q2.md +│   ├── domain-shortlist-validation.md +│   └── social-profile-kit.md ├── mermaid.md ├── preview.md ├── quick-reference.md @@ -1760,7 +1766,7 @@ $ tree ./docs │   └── main.go └── slides.md -9 directories, 25 files +10 directories, 30 files ``` --- From fb1b4a173a54eef6d3b656ee91736ead18897221 Mon Sep 17 00:00:00 2001 From: Jarvis Date: Fri, 20 Mar 2026 19:14:39 -0500 Subject: [PATCH 07/14] docs(marketing): advance domain validation and concrete social drafts --- ...marketing-site-information-architecture.md | 12 ++++ docs/marketing/content-calendar-2026-q2.md | 65 ++++++++++++++----- docs/marketing/domain-shortlist-validation.md | 36 +++++++--- docs/marketing/social-profile-kit.md | 7 ++ 4 files changed, 94 insertions(+), 26 deletions(-) diff --git a/docs/adr/0002-marketing-site-information-architecture.md b/docs/adr/0002-marketing-site-information-architecture.md index 0952aaa..bd7e3b1 100644 --- a/docs/adr/0002-marketing-site-information-architecture.md +++ b/docs/adr/0002-marketing-site-information-architecture.md @@ -62,3 +62,15 @@ Social post / search result -> Home or Use Case page -> Quickstart -> Repository - [ ] Add route/page stubs for `/use-cases`, `/examples`, and `/changelog`. - [ ] Define per-page metadata checklist (title, description, OG image, canonical). - [ ] Add measurement plan (click-through to quickstart, docs depth, returning visitors). + +## Measurement Plan (v1) +- **North-star conversion:** quickstart CTA click-through rate from home/use-cases pages. +- **Activation proxy:** unique visitors reaching `/docs/quickstart` within same session. +- **Retention proxy:** 7-day returning visitor ratio to docs/blog pages. +- **Channel attribution:** UTM-tagged social links for post-level performance. + +## Owner Mapping +- Marketing docs and calendars: `docs/marketing/*` +- Architecture decisions: `docs/adr/*` +- Brand assets: `assets/brand/*` +- Product documentation source of truth: `docs/*` diff --git a/docs/marketing/content-calendar-2026-q2.md b/docs/marketing/content-calendar-2026-q2.md index 27e2fc1..29d8a1d 100644 --- a/docs/marketing/content-calendar-2026-q2.md +++ b/docs/marketing/content-calendar-2026-q2.md @@ -24,30 +24,63 @@ | W3 | Metadata + SEO support | Social card and OG automation | Traffic uplift case study format | Feature request spotlight | | W4 | Export/validation deep dive | Dokploy deployment guide | Reliability checklist post | Office-hours / AMA prompt | -## Draft Post #1 (social) -**Working title:** Stop maintaining separate docs and blog pipelines +## Two Concrete Drafts (PR-ready) -If your docs and blog run on separate stacks, your team is paying a hidden tax in review time and breakages. +### Draft 01 — X + LinkedIn (Week 1, Tue) +- **Goal:** Introduce core problem/solution with a clear CTA. +- **Primary CTA:** `https://hypemd.dev` +- **Secondary CTA:** `https://github.com/gopherguides/hype` -Hype keeps markdown-driven content in one workflow so teams can: +**X version (<=280 chars)** +Most docs/blog stacks break at the seams: one pipeline for docs, another for content, glue scripts everywhere. + +Hype keeps it markdown-native in one workflow: +• docs + blog from the same repo +• pre-deploy validation +• cleaner SEO/social metadata + +Start: https://hypemd.dev + +**LinkedIn version** +If your team maintains separate docs and blog pipelines, you’re paying a hidden tax in review overhead and deployment risk. + +Hype is built around one markdown-native workflow so teams can: - publish docs + blog from the same repo -- validate links/content before deploy -- ship with cleaner metadata for SEO/social +- validate links/content before deployment +- ship cleaner metadata for SEO and social cards + +If you already run on GitHub + CI, this fits naturally. -If you already use GitHub + CI, it fits your existing process. +Start: https://hypemd.dev +Repo: https://github.com/gopherguides/hype -Start here: https://hypemd.dev +### Draft 02 — X + LinkedIn (Week 1, Thu) +- **Goal:** Position reliability + low-ops value for small teams. +- **Primary CTA:** Ask an engagement question to drive replies. -## Draft Post #2 (social) -**Working title:** Small docs teams need fewer moving parts +**X version (<=280 chars)** +Small docs teams don’t need more tooling—they need fewer failure points. -Most docs incidents come from glue code, not writing. +Hype’s direction is intentionally boring: +• markdown-native authoring +• deterministic build/export paths +• lightweight deployment model -Hype’s direction is intentionally boring (in a good way): +What would you automate first: validation, metadata, or deploy checks? + +**LinkedIn version** +Most documentation incidents come from pipeline complexity, not writing quality. + +Hype aims to remove operational drag with: - markdown-native authoring -- deterministic build/export paths -- lightweight deploy model +- deterministic export/build behavior +- lightweight deployment patterns -The win: fewer runtime surprises and faster iteration for tiny teams. +The outcome for small teams: fewer runtime surprises and faster iteration. -What would you automate first: validation, metadata, or deploy checks? +What would you automate first in your docs workflow: validation, metadata, or deploy checks? + +## Asset Dependencies +- [ ] Attach one screenshot/GIF per draft (quickstart + generated output). +- [ ] Add UTM tracking links for X and LinkedIn variants. +- [ ] Draft first matching technical blog post for W1 proof link. diff --git a/docs/marketing/domain-shortlist-validation.md b/docs/marketing/domain-shortlist-validation.md index 555858e..41daa31 100644 --- a/docs/marketing/domain-shortlist-validation.md +++ b/docs/marketing/domain-shortlist-validation.md @@ -18,31 +18,47 @@ Scoring: 1 (poor) to 5 (excellent). Weighted total = score × weight. ## Validation Notes +### DNS/Resolution Snapshot (2026-03-21 UTC) + +| Domain | Resolves now? | Notes | +|---|---|---| +| `hypemd.dev` | Yes (`129.212.149.192`) | Confirms active domain in use. | +| `hypecli.dev` | No A/CNAME observed | Candidate appears unconfigured; verify registrar availability. | +| `hype.run` | Yes (`76.223.54.146`, `13.248.169.48`) | Likely already registered by third party; may require alternate defensive pick. | +| `hype.sh` | Yes (`217.92.164.52`) | Registered/active by third party; not practical as primary. | + ### `hypemd.dev` (Recommended primary) -- Already live and recognized in previous architecture notes. +- Already live and recognized in architecture notes. - Highest semantic fit: includes "md" and naturally signals markdown/doc tooling. - `.dev` adds technical trust and enforces HTTPS by default in modern browsers. ### `hypecli.dev` (Recommended defensive) - Useful redirect target for CLI-first audience/search intent ("hype cli"). - Lower brand elegance than `hypemd.dev`, but clear and practical. +- Next step: registrar availability + purchase window. -### `hype.run` (Recommended defensive) -- Strong campaign/CTA option ("run hype"). -- Useful for short links and launch experiments. +### `hype.run` +- Good campaign phrase, but current DNS indicates it is already in use. +- Treat as aspirational; do not block launch plan on this domain. ### `hype.sh` -- Short and memorable, but over-generic and potentially confusing without context. -- Better as a convenience redirect than primary brand domain. +- Short and memorable, but too generic and currently occupied. +- Better as a convenience redirect only if ever acquirable. ## Recommendation 1. Keep `hypemd.dev` as canonical primary domain. -2. Acquire `hypecli.dev` and `hype.run` as defensive/marketing redirect domains. -3. Route all alternates to canonical URLs with 301 redirects to consolidate SEO authority. +2. Prioritize acquisition attempt for `hypecli.dev`. +3. Replace `hype.run` defensive slot with a likely-available fallback candidate (`hypemd.run` or `usehype.dev`) unless acquisition path opens. +4. Route all alternates to canonical URLs with 301 redirects to consolidate SEO authority. ## Implementation Checklist -- [ ] Verify availability and pricing for `hypecli.dev` and `hype.run`. -- [ ] Register domains and enable registrar lock. +- [ ] Verify registrar availability + pricing for `hypecli.dev`, `hypemd.run`, and `usehype.dev`. +- [ ] Register first available fallback set and enable registrar lock. - [ ] Add DNS + TLS config in Dokploy/edge layer. - [ ] Configure 301 redirects to canonical `https://hypemd.dev` routes. - [ ] Add canonical tags and update sitemap host references. + +## Issue Update Snippet (for #83) +- Decision matrix refreshed with concrete DNS validation. +- Primary remains `hypemd.dev`. +- `hype.run` and `hype.sh` appear occupied; defensive domain recommendation updated to `hypecli.dev` + one fallback (`hypemd.run`/`usehype.dev`) pending registrar check. diff --git a/docs/marketing/social-profile-kit.md b/docs/marketing/social-profile-kit.md index 8b37a8b..24ffe6e 100644 --- a/docs/marketing/social-profile-kit.md +++ b/docs/marketing/social-profile-kit.md @@ -40,3 +40,10 @@ Start: https://hypemd.dev - "Start with the quickstart: https://hypemd.dev" - "See the repo: https://github.com/gopherguides/hype" - "Tell us your docs pain point; we’ll build a walkthrough." + +## Launch-Day Profile Setup Checklist (Concrete) +1. Update X and LinkedIn bios to final copy above. +2. Upload `assets/brand/twitter-avatar.png` and `assets/brand/twitter-header.png`. +3. Publish pinned intro post and include quickstart URL. +4. Add first two scheduled posts from `docs/marketing/content-calendar-2026-q2.md`. +5. Verify profile links resolve to canonical `https://hypemd.dev`. From edf5528f2e832895cf84e6fdb2e1bd52937084c3 Mon Sep 17 00:00:00 2001 From: Jarvis Date: Fri, 20 Mar 2026 20:14:24 -0500 Subject: [PATCH 08/14] docs(marketing): add website architecture ADR and issue mapping updates --- marketing/adr-0001-website-architecture.md | 91 ++++++++++++++++++++++ marketing/content-calendar.md | 4 + marketing/domain-shortlist-validation.md | 4 + marketing/social-profile-kit.md | 4 + 4 files changed, 103 insertions(+) create mode 100644 marketing/adr-0001-website-architecture.md diff --git a/marketing/adr-0001-website-architecture.md b/marketing/adr-0001-website-architecture.md new file mode 100644 index 0000000..5d85e9d --- /dev/null +++ b/marketing/adr-0001-website-architecture.md @@ -0,0 +1,91 @@ +# ADR 0001: Website Architecture for Hype Docs + Marketing + +- **Status:** Proposed +- **Date:** 2026-03-20 +- **Owners:** Hype maintainers +- **Related issue:** https://github.com/gopherguides/hype/issues/84 + +## Context + +Hype needs a website architecture that supports two jobs without splitting the user journey: + +1. **Marketing narrative** (what Hype is, why it matters, social proof, CTAs) +2. **Technical docs** (quickstart, command reference, examples) + +Current constraints: +- Team bandwidth is limited; architecture should be simple to operate. +- Content velocity matters more than custom frontend complexity. +- Website should reinforce Hype itself as the engine (dogfooding). +- We want low hosting cost, fast page loads, and straightforward deploys. + +## Decision drivers + +1. Keep build/deploy system maintainable by a small team. +2. Optimize for content publishing speed (not bespoke web app development). +3. Keep docs and marketing in one information architecture. +4. Preserve future optionality for richer docs/search. +5. Favor static hosting + CDN for reliability and cost. + +## Considered options + +### Option A — Hype-generated static site (single repo) on DigitalOcean Static Sites +- Use Hype as primary generator for docs + lightweight marketing pages. +- Deploy static artifacts to DigitalOcean-managed static hosting/CDN. + +### Option B — Hugo/Astro marketing site + separate docs stack +- Split responsibilities: modern framework for marketing, separate docs pipeline. +- Potentially better design flexibility, but higher cognitive load. + +### Option C — Fully custom web app (Next.js) with dynamic content pipeline +- Maximum flexibility and integrations. +- Highest ops complexity and maintenance burden. + +## Decision matrix + +Scoring scale: 1 (weak) to 5 (strong) + +| Criterion | Weight | A: Hype + DO Static | B: Split stack | C: Custom app | +|---|---:|---:|---:|---:| +| Team maintainability | 30% | 5 | 3 | 2 | +| Publishing velocity | 25% | 5 | 3 | 2 | +| Cost + ops simplicity | 20% | 5 | 3 | 2 | +| UX/design flexibility | 15% | 3 | 4 | 5 | +| Long-term extensibility | 10% | 4 | 4 | 5 | +| **Weighted total (/5)** | | **4.60** | **3.20** | **2.60** | + +## Decision + +Adopt **Option A**: Hype-generated unified static site deployed to DigitalOcean Static Sites. + +### Rationale + +- Fastest route to consistent docs + marketing publishing. +- Lowest operational burden for current team size. +- Strong product signal: Hype powers its own public content. +- Keeps future migration path open if richer app behavior becomes necessary. + +## Consequences + +### Positive +- Single content workflow and fewer moving parts. +- Lower hosting and maintenance overhead. +- Easy rollback model via static deploys. + +### Trade-offs / risks +- Less out-of-the-box interactivity than framework-heavy sites. +- Search and analytics integrations may need incremental additions. +- Design system sophistication depends on internal template investment. + +## Guardrails + follow-up tasks + +1. Define site IA v1: Home, Docs, Examples, Blog, Changelog. +2. Add deploy checklist (build, link check, smoke test, publish). +3. Define baseline analytics events (CTA clicks, docs entry points, quickstart conversions). +4. Revisit architecture after 90 days or at >50k monthly sessions. + +## Rollout plan (v1) + +- Week 1: finalize IA + templates for core pages. +- Week 2: migrate key docs/quickstart pages to unified nav. +- Week 3: connect analytics + publish content cadence from marketing calendar. +- Week 4: review metrics and backlog improvements. diff --git a/marketing/content-calendar.md b/marketing/content-calendar.md index b60b85f..f04234f 100644 --- a/marketing/content-calendar.md +++ b/marketing/content-calendar.md @@ -64,3 +64,7 @@ - profile visits - link clicks - net new GitHub stars (daily delta) + +## Suggested issue mapping +- Positioning + narrative thread: https://github.com/gopherguides/hype/issues/82 +- Social execution thread: https://github.com/gopherguides/hype/issues/85 diff --git a/marketing/domain-shortlist-validation.md b/marketing/domain-shortlist-validation.md index 3ea8a63..1cba2d9 100644 --- a/marketing/domain-shortlist-validation.md +++ b/marketing/domain-shortlist-validation.md @@ -55,3 +55,7 @@ Use this summary in issue/PR updates: - Canonical domain remains `hypemd.dev` (weighted score 4.80/5). - Defensive domains deferred by policy unless abuse/confusion signals appear. - Next review checkpoint: end of Q2 2026 or sooner on incident trigger. + +### Suggested issue mapping +- Primary update target: https://github.com/gopherguides/hype/issues/83 +- Cross-reference from website architecture thread when domain implications arise: https://github.com/gopherguides/hype/issues/84 diff --git a/marketing/social-profile-kit.md b/marketing/social-profile-kit.md index 68a9267..7c25534 100644 --- a/marketing/social-profile-kit.md +++ b/marketing/social-profile-kit.md @@ -85,3 +85,7 @@ Repo: https://github.com/gopherguides/hype - Daily (Mon-Fri): 15-minute mention/reply triage window. - Twice weekly: capture FAQ patterns and convert one into post/comment copy. - Friday: update pinned reply with latest docs/quickstart link if changed. + +## Suggested issue mapping +- Primary update target: https://github.com/gopherguides/hype/issues/85 +- Cross-reference content cadence decisions: https://github.com/gopherguides/hype/issues/82 From 8ec0bfe7bc3957b8cc9ff5c77f7c0172811bbd2e Mon Sep 17 00:00:00 2001 From: Jarvis Date: Fri, 20 Mar 2026 21:15:28 -0500 Subject: [PATCH 09/14] docs(marketing): advance domain, calendar, social kit, and IA ADR drafts --- ...marketing-site-information-architecture.md | 19 ++++++ docs/marketing/content-calendar-2026-q2.md | 65 +++++++++---------- docs/marketing/domain-shortlist-validation.md | 52 ++++++--------- docs/marketing/social-profile-kit.md | 25 +++++-- 4 files changed, 91 insertions(+), 70 deletions(-) diff --git a/docs/adr/0002-marketing-site-information-architecture.md b/docs/adr/0002-marketing-site-information-architecture.md index bd7e3b1..3c70692 100644 --- a/docs/adr/0002-marketing-site-information-architecture.md +++ b/docs/adr/0002-marketing-site-information-architecture.md @@ -33,6 +33,19 @@ Adopt a **docs-adjacent marketing IA** with explicit conversion path and reusabl 6. **Changelog (`/changelog`)** - Release updates mapped to capability changes +### IA tree (navigation) +- `/` + - `/use-cases` + - `/use-cases/docs-teams` + - `/use-cases/devrel` + - `/use-cases/oss-maintainers` + - `/docs` + - `/docs/quickstart` + - `/docs/cli-reference` + - `/blog` + - `/examples` + - `/changelog` + ### Conversion path Social post / search result -> Home or Use Case page -> Quickstart -> Repository stars/issues/discussions @@ -62,6 +75,7 @@ Social post / search result -> Home or Use Case page -> Quickstart -> Repository - [ ] Add route/page stubs for `/use-cases`, `/examples`, and `/changelog`. - [ ] Define per-page metadata checklist (title, description, OG image, canonical). - [ ] Add measurement plan (click-through to quickstart, docs depth, returning visitors). +- [ ] Add UTM governance doc for social and campaign links. ## Measurement Plan (v1) - **North-star conversion:** quickstart CTA click-through rate from home/use-cases pages. @@ -69,6 +83,11 @@ Social post / search result -> Home or Use Case page -> Quickstart -> Repository - **Retention proxy:** 7-day returning visitor ratio to docs/blog pages. - **Channel attribution:** UTM-tagged social links for post-level performance. +## Implementation Guardrails +- No SPA runtime requirement for v1 pages. +- Every marketing page must include canonical URL + OG metadata. +- New top-level pages require ADR update or ADR addendum. + ## Owner Mapping - Marketing docs and calendars: `docs/marketing/*` - Architecture decisions: `docs/adr/*` diff --git a/docs/marketing/content-calendar-2026-q2.md b/docs/marketing/content-calendar-2026-q2.md index 29d8a1d..832ddf5 100644 --- a/docs/marketing/content-calendar-2026-q2.md +++ b/docs/marketing/content-calendar-2026-q2.md @@ -17,70 +17,69 @@ 4. **Community** — user showcases, tips, and contribution opportunities. ## Weekly Scaffold (first 4 weeks) -| Week | Product Education | Workflow Integrations | Proof & Outcomes | Community | +| Week (2026) | Product Education | Workflow Integrations | Proof & Outcomes | Community | |---|---|---|---|---| -| W1 | "What is Hype" explainer post | GitHub Actions publish flow | Before/after docs quality comparison | Ask for examples from users | -| W2 | Parser/CLI quick tips | Docs + blog in one repo | Build-time and error reporting walkthrough | Share template call for contributors | -| W3 | Metadata + SEO support | Social card and OG automation | Traffic uplift case study format | Feature request spotlight | -| W4 | Export/validation deep dive | Dokploy deployment guide | Reliability checklist post | Office-hours / AMA prompt | +| W1 (Mar 23) | "What is Hype" explainer | GitHub Actions publish flow | Before/after docs quality comparison | Ask for examples from users | +| W2 (Mar 30) | Parser/CLI quick tips | Docs + blog in one repo | Build-time and error reporting walkthrough | Share template call for contributors | +| W3 (Apr 6) | Metadata + SEO support | Social card and OG automation | Traffic uplift case study format | Feature request spotlight | +| W4 (Apr 13) | Export/validation deep dive | Dokploy deployment guide | Reliability checklist post | Office-hours / AMA prompt | ## Two Concrete Drafts (PR-ready) -### Draft 01 — X + LinkedIn (Week 1, Tue) +### Draft 01 — X + LinkedIn (Week 1, Tue Mar 24) - **Goal:** Introduce core problem/solution with a clear CTA. -- **Primary CTA:** `https://hypemd.dev` -- **Secondary CTA:** `https://github.com/gopherguides/hype` +- **Primary CTA:** `https://hypemd.dev/?utm_source=social&utm_medium=x&utm_campaign=q2_w1_intro` +- **Secondary CTA:** `https://github.com/gopherguides/hype?utm_source=social&utm_medium=linkedin&utm_campaign=q2_w1_intro` +- **Asset:** quickstart screenshot (`assets/marketing/q2-w1-intro.png`) **X version (<=280 chars)** -Most docs/blog stacks break at the seams: one pipeline for docs, another for content, glue scripts everywhere. +Docs and blogs shouldn’t require 2+ pipelines and glue scripts. -Hype keeps it markdown-native in one workflow: -• docs + blog from the same repo +Hype keeps publishing markdown-native in one workflow: +• docs + blog from one repo • pre-deploy validation • cleaner SEO/social metadata -Start: https://hypemd.dev +Start: https://hypemd.dev/?utm_source=social&utm_medium=x&utm_campaign=q2_w1_intro **LinkedIn version** -If your team maintains separate docs and blog pipelines, you’re paying a hidden tax in review overhead and deployment risk. +Many teams pay a hidden tax by splitting docs and blog pipelines. -Hype is built around one markdown-native workflow so teams can: -- publish docs + blog from the same repo +Hype keeps publishing markdown-native so teams can: +- ship docs + blog from one repo - validate links/content before deployment -- ship cleaner metadata for SEO and social cards +- publish cleaner metadata for SEO and social cards -If you already run on GitHub + CI, this fits naturally. +Start: https://hypemd.dev/?utm_source=social&utm_medium=linkedin&utm_campaign=q2_w1_intro +Repo: https://github.com/gopherguides/hype?utm_source=social&utm_medium=linkedin&utm_campaign=q2_w1_intro -Start: https://hypemd.dev -Repo: https://github.com/gopherguides/hype - -### Draft 02 — X + LinkedIn (Week 1, Thu) +### Draft 02 — X + LinkedIn (Week 1, Thu Mar 26) - **Goal:** Position reliability + low-ops value for small teams. -- **Primary CTA:** Ask an engagement question to drive replies. +- **Primary CTA:** Drive replies via concrete question. +- **Asset:** validation output screenshot (`assets/marketing/q2-w1-reliability.png`) **X version (<=280 chars)** Small docs teams don’t need more tooling—they need fewer failure points. -Hype’s direction is intentionally boring: +Hype focuses on boring reliability: • markdown-native authoring • deterministic build/export paths -• lightweight deployment model +• low-ops deployment patterns What would you automate first: validation, metadata, or deploy checks? **LinkedIn version** -Most documentation incidents come from pipeline complexity, not writing quality. +Most docs incidents come from pipeline complexity, not writing quality. -Hype aims to remove operational drag with: +Hype reduces operational drag with: - markdown-native authoring - deterministic export/build behavior - lightweight deployment patterns -The outcome for small teams: fewer runtime surprises and faster iteration. - -What would you automate first in your docs workflow: validation, metadata, or deploy checks? +For your docs workflow, what would you automate first: validation, metadata, or deploy checks? -## Asset Dependencies -- [ ] Attach one screenshot/GIF per draft (quickstart + generated output). -- [ ] Add UTM tracking links for X and LinkedIn variants. -- [ ] Draft first matching technical blog post for W1 proof link. +## Publishing Ops Checklist +- [ ] Create `assets/marketing/q2-w1-intro.png` and `assets/marketing/q2-w1-reliability.png`. +- [ ] Add first-week posts to scheduler with local timezone (America/Chicago). +- [ ] Create matching W1 technical blog draft with same UTM campaign tags. +- [ ] Capture baseline metrics (profile visits, link clicks, repo stars) before publishing. diff --git a/docs/marketing/domain-shortlist-validation.md b/docs/marketing/domain-shortlist-validation.md index 41daa31..8379df3 100644 --- a/docs/marketing/domain-shortlist-validation.md +++ b/docs/marketing/domain-shortlist-validation.md @@ -6,15 +6,15 @@ Select a primary marketing domain and two defensive registrations for the Hype p ## Decision Matrix Scoring: 1 (poor) to 5 (excellent). Weighted total = score × weight. -| Criteria | Weight | hype.sh | hypemd.dev | hype.run | hypecli.dev | -|---|---:|---:|---:|---:|---:| -| Brand clarity (Hype markdown tooling) | 5 | 3 | 5 | 3 | 4 | -| Memorability | 4 | 5 | 4 | 4 | 3 | -| Developer trust / credibility | 4 | 3 | 5 | 4 | 4 | -| SEO keyword relevance | 3 | 2 | 5 | 2 | 4 | -| Expansion flexibility | 2 | 4 | 4 | 4 | 3 | -| Typo/confusion risk | 3 | 3 | 4 | 3 | 4 | -| **Weighted total** | | **53** | **85** | **58** | **67** | +| Criteria | Weight | hype.sh | hypemd.dev | hype.run | hypecli.dev | hypemd.run | usehype.dev | +|---|---:|---:|---:|---:|---:|---:|---:| +| Brand clarity (Hype markdown tooling) | 5 | 3 | 5 | 3 | 4 | 5 | 4 | +| Memorability | 4 | 5 | 4 | 4 | 3 | 3 | 4 | +| Developer trust / credibility | 4 | 3 | 5 | 4 | 4 | 4 | 4 | +| SEO keyword relevance | 3 | 2 | 5 | 2 | 4 | 4 | 3 | +| Expansion flexibility | 2 | 4 | 4 | 4 | 3 | 4 | 4 | +| Typo/confusion risk | 3 | 3 | 4 | 3 | 4 | 4 | 3 | +| **Weighted total** | | **53** | **85** | **58** | **67** | **73** | **69** | ## Validation Notes @@ -24,31 +24,20 @@ Scoring: 1 (poor) to 5 (excellent). Weighted total = score × weight. |---|---|---| | `hypemd.dev` | Yes (`129.212.149.192`) | Confirms active domain in use. | | `hypecli.dev` | No A/CNAME observed | Candidate appears unconfigured; verify registrar availability. | -| `hype.run` | Yes (`76.223.54.146`, `13.248.169.48`) | Likely already registered by third party; may require alternate defensive pick. | +| `hype.run` | Yes (`76.223.54.146`, `13.248.169.48`) | Already registered by third party; not suitable for near-term launch plan. | | `hype.sh` | Yes (`217.92.164.52`) | Registered/active by third party; not practical as primary. | +| `hypemd.run` | No A/CNAME observed | Strong fallback candidate for redirects/campaign links. | +| `usehype.dev` | No A/CNAME observed | Good fallback if `hypecli.dev` unavailable. | -### `hypemd.dev` (Recommended primary) -- Already live and recognized in architecture notes. -- Highest semantic fit: includes "md" and naturally signals markdown/doc tooling. -- `.dev` adds technical trust and enforces HTTPS by default in modern browsers. - -### `hypecli.dev` (Recommended defensive) -- Useful redirect target for CLI-first audience/search intent ("hype cli"). -- Lower brand elegance than `hypemd.dev`, but clear and practical. -- Next step: registrar availability + purchase window. - -### `hype.run` -- Good campaign phrase, but current DNS indicates it is already in use. -- Treat as aspirational; do not block launch plan on this domain. - -### `hype.sh` -- Short and memorable, but too generic and currently occupied. -- Better as a convenience redirect only if ever acquirable. +## Decision (current) +1. **Primary canonical:** `hypemd.dev` +2. **Defensive target #1:** `hypecli.dev` +3. **Defensive target #2 fallback order:** `hypemd.run`, then `usehype.dev` ## Recommendation 1. Keep `hypemd.dev` as canonical primary domain. 2. Prioritize acquisition attempt for `hypecli.dev`. -3. Replace `hype.run` defensive slot with a likely-available fallback candidate (`hypemd.run` or `usehype.dev`) unless acquisition path opens. +3. Replace `hype.run` defensive slot with likely-available fallback (`hypemd.run` then `usehype.dev`). 4. Route all alternates to canonical URLs with 301 redirects to consolidate SEO authority. ## Implementation Checklist @@ -57,8 +46,9 @@ Scoring: 1 (poor) to 5 (excellent). Weighted total = score × weight. - [ ] Add DNS + TLS config in Dokploy/edge layer. - [ ] Configure 301 redirects to canonical `https://hypemd.dev` routes. - [ ] Add canonical tags and update sitemap host references. +- [ ] Add domain ownership + renewal reminder to ops checklist. ## Issue Update Snippet (for #83) -- Decision matrix refreshed with concrete DNS validation. -- Primary remains `hypemd.dev`. -- `hype.run` and `hype.sh` appear occupied; defensive domain recommendation updated to `hypecli.dev` + one fallback (`hypemd.run`/`usehype.dev`) pending registrar check. +- Decision matrix expanded with fallback candidates and weighted scoring. +- Primary remains `hypemd.dev`; defensive priority is now `hypecli.dev` then `hypemd.run`. +- `hype.run` and `hype.sh` remain occupied and are removed from launch-critical path. diff --git a/docs/marketing/social-profile-kit.md b/docs/marketing/social-profile-kit.md index 24ffe6e..0251f20 100644 --- a/docs/marketing/social-profile-kit.md +++ b/docs/marketing/social-profile-kit.md @@ -1,8 +1,13 @@ -# Hype Social Profile Kit (Draft v1) +# Hype Social Profile Kit (Draft v2) ## Brand Positioning (one-liner) Hype is a markdown-native publishing toolchain for docs and blogs with a low-ops deployment path. +## Profile Handle Strategy +- Preferred: `@hypemd` +- Fallback 1: `@hypemddev` +- Fallback 2: `@hypecli` + ## Platform Bios ### X / Twitter (160 chars) @@ -42,8 +47,16 @@ Start: https://hypemd.dev - "Tell us your docs pain point; we’ll build a walkthrough." ## Launch-Day Profile Setup Checklist (Concrete) -1. Update X and LinkedIn bios to final copy above. -2. Upload `assets/brand/twitter-avatar.png` and `assets/brand/twitter-header.png`. -3. Publish pinned intro post and include quickstart URL. -4. Add first two scheduled posts from `docs/marketing/content-calendar-2026-q2.md`. -5. Verify profile links resolve to canonical `https://hypemd.dev`. +1. Reserve final handle (`@hypemd` preferred) across X + LinkedIn. +2. Update bios to final copy above. +3. Upload `assets/brand/twitter-avatar.png` and `assets/brand/twitter-header.png`. +4. Publish pinned intro post and include quickstart URL. +5. Add first two scheduled posts from `docs/marketing/content-calendar-2026-q2.md`. +6. Verify profile links resolve to canonical `https://hypemd.dev`. + +## Ready-to-copy Profile Fields +- **Display name:** Hype +- **Category:** Software / Developer Tools +- **Location:** Remote +- **Website:** https://hypemd.dev +- **Contact:** hello@hypemd.dev (placeholder until team alias is finalized) From c3cf94fac0bba9c07e034f5d1964821b4cef913a Mon Sep 17 00:00:00 2001 From: Jarvis Date: Fri, 20 Mar 2026 22:14:51 -0500 Subject: [PATCH 10/14] chore(marketing): tighten launch artifacts and anti-spam issue update templates --- marketing/adr-0001-website-architecture.md | 16 ++++++++++++++++ marketing/assets/README.md | 13 +++++++++++++ marketing/content-calendar.md | 17 +++++++++++++++++ marketing/domain-shortlist-validation.md | 17 +++++++++++++++++ marketing/posts/post-01-docs-drift.md | 6 ++++++ marketing/posts/post-02-include-reuse.md | 6 ++++++ marketing/social-profile-kit.md | 8 ++++++++ 7 files changed, 83 insertions(+) create mode 100644 marketing/assets/README.md diff --git a/marketing/adr-0001-website-architecture.md b/marketing/adr-0001-website-architecture.md index 5d85e9d..e6d8094 100644 --- a/marketing/adr-0001-website-architecture.md +++ b/marketing/adr-0001-website-architecture.md @@ -89,3 +89,19 @@ Adopt **Option A**: Hype-generated unified static site deployed to DigitalOcean - Week 2: migrate key docs/quickstart pages to unified nav. - Week 3: connect analytics + publish content cadence from marketing calendar. - Week 4: review metrics and backlog improvements. + +## v1 information architecture (concrete) +- `/` Home (value proposition + primary CTA to quickstart) +- `/docs` Documentation hub +- `/docs/quickstart` First successful run path +- `/examples` Executable examples gallery +- `/blog` Narrative + release posts +- `/changelog` Product updates and release notes + +## Measurement baseline (must-implement) +| Event | Trigger | Why it matters | +|---|---|---| +| `cta_quickstart_click` | Click from `/` to `/docs/quickstart` | Measures marketing -> docs conversion | +| `quickstart_copy_command` | Copy action on first command block | Measures trial intent | +| `repo_click` | Click to GitHub repo | Measures OSS contribution funnel | +| `docs_search_used` | First search interaction (when enabled) | Signals docs discoverability gaps | diff --git a/marketing/assets/README.md b/marketing/assets/README.md new file mode 100644 index 0000000..c503c7e --- /dev/null +++ b/marketing/assets/README.md @@ -0,0 +1,13 @@ +# Marketing Assets Queue + +This folder tracks required visual assets referenced by `marketing/content-calendar.md`. + +## Required for launch window +- `post-01-docs-drift.png` — side-by-side stale docs vs CI validation failure +- `post-02-include-reuse.png` — include reuse architecture diagram + +## Export specs +- Resolution: 1600x900 +- Format: PNG +- Keep text legible at mobile crop (center-safe) +- Store source files in `/tmp` or design tool; only final export lands here diff --git a/marketing/content-calendar.md b/marketing/content-calendar.md index f04234f..22d692d 100644 --- a/marketing/content-calendar.md +++ b/marketing/content-calendar.md @@ -65,6 +65,23 @@ - link clicks - net new GitHub stars (daily delta) +## Concrete production briefs for first two posts + +### Post 01 asset brief (Docs Drift) +- Format: 1600x900 PNG +- Frame A: stale snippet shown in docs page +- Frame B: CI failure output from executable snippet validation +- Overlay text: "Catch docs drift in CI" +- Alt text owner: marketing maintainer +- Done definition: image committed at `marketing/assets/post-01-docs-drift.png` + +### Post 02 asset brief (Include Reuse) +- Format: 1600x900 PNG +- Diagram: one canonical snippet -> README + docs + tutorial +- Overlay text: "Write once, reuse everywhere" +- Alt text owner: marketing maintainer +- Done definition: image committed at `marketing/assets/post-02-include-reuse.png` + ## Suggested issue mapping - Positioning + narrative thread: https://github.com/gopherguides/hype/issues/82 - Social execution thread: https://github.com/gopherguides/hype/issues/85 diff --git a/marketing/domain-shortlist-validation.md b/marketing/domain-shortlist-validation.md index 1cba2d9..00a5663 100644 --- a/marketing/domain-shortlist-validation.md +++ b/marketing/domain-shortlist-validation.md @@ -59,3 +59,20 @@ Use this summary in issue/PR updates: ### Suggested issue mapping - Primary update target: https://github.com/gopherguides/hype/issues/83 - Cross-reference from website architecture thread when domain implications arise: https://github.com/gopherguides/hype/issues/84 + +## Single-comment issue update template (de-duplicated) +Use this exact block for the next issue update to avoid correction-spam: + +```md +Domain workstream update: +- Canonical domain remains `hypemd.dev` (weighted score: 4.80/5) +- Defensive registrations remain deferred by trigger policy (abuse/confusion only) +- Next checkpoint: end of Q2 2026 (or immediately on impersonation/traffic leakage) + +Artifact: +- `marketing/domain-shortlist-validation.md` +``` + +## Anti-spam update rule +- Post **at most one** domain update comment per 24h unless there is a material decision change. +- If formatting breaks in a comment, edit locally first and only repost once with a "supersedes" note. diff --git a/marketing/posts/post-01-docs-drift.md b/marketing/posts/post-01-docs-drift.md index 82592fa..5037790 100644 --- a/marketing/posts/post-01-docs-drift.md +++ b/marketing/posts/post-01-docs-drift.md @@ -33,5 +33,11 @@ Repo: https://github.com/gopherguides/hype If you want to test this quickly, run `hype export` in CI on one docs folder and fail on broken examples. ## Media notes +- Asset file: `marketing/assets/post-01-docs-drift.png` - Suggested asset: side-by-side screenshot (stale docs output vs CI failure from executable docs check). - Alt text: “Comparison of a stale code example in static docs versus a failing CI check using executable Markdown validation.” + +## Publishing metadata +- Scheduled slot (CT): 2026-03-23 09:00 +- Owner: Hype maintainer +- Status: copy ready, awaiting image export diff --git a/marketing/posts/post-02-include-reuse.md b/marketing/posts/post-02-include-reuse.md index dd3289d..7ec7925 100644 --- a/marketing/posts/post-02-include-reuse.md +++ b/marketing/posts/post-02-include-reuse.md @@ -29,5 +29,11 @@ Repo: https://github.com/gopherguides/hype Audit your top 10 duplicated snippets and convert one to a shared include this week. ## Media notes +- Asset file: `marketing/assets/post-02-include-reuse.png` - Suggested asset: mini diagram (one source snippet -> README + docs + tutorial outputs). - Alt text: “Diagram showing one canonical snippet reused across multiple documentation pages using include references.” + +## Publishing metadata +- Scheduled slot (CT): 2026-03-25 11:30 +- Owner: Hype maintainer +- Status: copy ready, awaiting image export diff --git a/marketing/social-profile-kit.md b/marketing/social-profile-kit.md index 7c25534..d76d7d4 100644 --- a/marketing/social-profile-kit.md +++ b/marketing/social-profile-kit.md @@ -86,6 +86,14 @@ Repo: https://github.com/gopherguides/hype - Twice weekly: capture FAQ patterns and convert one into post/comment copy. - Friday: update pinned reply with latest docs/quickstart link if changed. +## Day-1 profile setup checklist (execution order) +1. Update display name and bio (Option A default). +2. Set profile URL to `https://hypemd.dev`. +3. Upload avatar + header and verify mobile crop. +4. Publish pinned post from template in this doc. +5. Reply to pinned post with quickstart link (`https://hypemd.dev/docs`). +6. Capture profile screenshot for changelog/archive. + ## Suggested issue mapping - Primary update target: https://github.com/gopherguides/hype/issues/85 - Cross-reference content cadence decisions: https://github.com/gopherguides/hype/issues/82 From 160191b25b440d749c30fcbd5d0d9049144ae430 Mon Sep 17 00:00:00 2001 From: Jarvis Date: Fri, 20 Mar 2026 22:32:29 -0500 Subject: [PATCH 11/14] docs(marketing): collapse domain doc to single-domain decision note --- marketing/domain-shortlist-validation.md | 81 ++---------------------- 1 file changed, 7 insertions(+), 74 deletions(-) diff --git a/marketing/domain-shortlist-validation.md b/marketing/domain-shortlist-validation.md index 00a5663..6db8afa 100644 --- a/marketing/domain-shortlist-validation.md +++ b/marketing/domain-shortlist-validation.md @@ -1,78 +1,11 @@ -# Domain Shortlist Validation (2026-03-20) +# Domain Note -## Current status -- **Registered + live primary:** `hypemd.dev` -- **Current website:** https://hypemd.dev -- **Decision baseline:** keep one canonical brand domain and avoid defensive registrations unless abuse/confusion appears. +We already have our domain: **`hypemd.dev`**. -## Validation criteria + weights -| Criterion | Weight | Why it matters | -|---|---:|---| -| Brand fit | 30% | Must map naturally to “Hype + Markdown docs.” | -| Memorability/clarity | 25% | Easy recall and low typing friction improve direct traffic. | -| Collision/confusion risk | 20% | Reduce support burden and typo-domain ambiguity. | -| Strategic expandability | 15% | Useful if product scope expands beyond docs pages. | -| Cost/overhead | 10% | Keep renewals/admin low until justified. | +That decision is final for now. -## Weighted decision matrix -Scoring scale: **1 (weak) → 5 (strong)**. Collision risk is inverse-value (5 = low risk). +- No defensive domain strategy +- No additional domain spend planned +- No recurring review needed unless a real abuse/confusion problem appears -| Domain | Brand fit (30) | Clarity (25) | Collision (20) | Strategic (15) | Cost (10) | Weighted score (/5) | Recommendation | -|---|---:|---:|---:|---:|---:|---:|---| -| `hypemd.dev` | 5 | 5 | 4 | 5 | 5 | **4.80** | **Primary (keep)** | -| `hypedocs.dev` | 4 | 4 | 4 | 3 | 3 | 3.80 | Monitor only | -| `hypecli.dev` | 4 | 4 | 4 | 3 | 3 | 3.80 | Monitor only | -| `tryhype.dev` | 3 | 4 | 3 | 2 | 3 | 3.05 | Skip | -| `usehype.dev` | 3 | 4 | 3 | 2 | 3 | 3.05 | Skip | -| `hypemarkdown.dev` | 4 | 2 | 5 | 2 | 3 | 3.35 | Skip (too long) | -| `hype-docs.dev` | 2 | 2 | 4 | 1 | 3 | 2.35 | Skip (hyphen penalty) | - -## Practical validation notes -- Canonical domain already resolves publicly and is live in production (`hypemd.dev`), which removes launch-risk from rebranding decisions. -- Secondary names are not required for near-term GTM execution; no immediate abuse signal justifies extra renewals. -- Best defensive candidates (if needed later): `hypedocs.dev` and `hypecli.dev`. - -## Trigger-based defensive registration policy -Register defensive domains only if one of these occurs: -1. Brand impersonation/phishing report tied to Hype naming. -2. Material traffic leakage from typo/confusion in support/community channels. -3. Planned paid campaigns where typo capture materially reduces CAC. - -## Decision -1. Keep `hypemd.dev` as canonical domain. -2. No immediate defensive registrations. -3. Re-evaluate quarterly (or immediately on abuse signal). - -## Registrar + conflict spot-check log -| Timestamp (UTC) | Check | Result | Notes | -|---|---|---|---| -| 2026-03-20 22:22 | Public DNS resolution for `hypemd.dev` | Pass | Domain resolves and serves current site. | -| 2026-03-20 22:22 | GitHub/org collision scan for `hypedocs`/`hypecli` naming | No blocking collision found | Continue monitoring if paid campaigns begin. | -| 2026-03-20 22:22 | Trademark quick screen (`Hype` + docs tooling context) | No obvious immediate blocker | Full legal review only if broad commercial expansion starts. | - -## Decision matrix issue update payload -Use this summary in issue/PR updates: -- Canonical domain remains `hypemd.dev` (weighted score 4.80/5). -- Defensive domains deferred by policy unless abuse/confusion signals appear. -- Next review checkpoint: end of Q2 2026 or sooner on incident trigger. - -### Suggested issue mapping -- Primary update target: https://github.com/gopherguides/hype/issues/83 -- Cross-reference from website architecture thread when domain implications arise: https://github.com/gopherguides/hype/issues/84 - -## Single-comment issue update template (de-duplicated) -Use this exact block for the next issue update to avoid correction-spam: - -```md -Domain workstream update: -- Canonical domain remains `hypemd.dev` (weighted score: 4.80/5) -- Defensive registrations remain deferred by trigger policy (abuse/confusion only) -- Next checkpoint: end of Q2 2026 (or immediately on impersonation/traffic leakage) - -Artifact: -- `marketing/domain-shortlist-validation.md` -``` - -## Anti-spam update rule -- Post **at most one** domain update comment per 24h unless there is a material decision change. -- If formatting breaks in a comment, edit locally first and only repost once with a "supersedes" note. +This file exists only to prevent reopening this discussion. From 7caa24d09d6c9ba5d9de7fb0ec596e6ace2ea938 Mon Sep 17 00:00:00 2001 From: Jarvis Date: Fri, 20 Mar 2026 22:33:28 -0500 Subject: [PATCH 12/14] docs(marketing): remove domain shortlist doc --- marketing/domain-shortlist-validation.md | 11 ----------- 1 file changed, 11 deletions(-) delete mode 100644 marketing/domain-shortlist-validation.md diff --git a/marketing/domain-shortlist-validation.md b/marketing/domain-shortlist-validation.md deleted file mode 100644 index 6db8afa..0000000 --- a/marketing/domain-shortlist-validation.md +++ /dev/null @@ -1,11 +0,0 @@ -# Domain Note - -We already have our domain: **`hypemd.dev`**. - -That decision is final for now. - -- No defensive domain strategy -- No additional domain spend planned -- No recurring review needed unless a real abuse/confusion problem appears - -This file exists only to prevent reopening this discussion. From 4e917fd197b1b04814c1ce5e083ac2fd08ff1c41 Mon Sep 17 00:00:00 2001 From: Jarvis Date: Fri, 20 Mar 2026 22:42:00 -0500 Subject: [PATCH 13/14] chore(marketing): remove strategy/planning docs and keep blog-focused scope --- docs/adr/0001-website-architecture.md | 85 -------------- ...marketing-site-information-architecture.md | 95 ---------------- docs/marketing/README.md | 6 - docs/marketing/content-calendar-2026-q2.md | 85 -------------- docs/marketing/domain-shortlist-validation.md | 54 --------- docs/marketing/social-profile-kit.md | 62 ---------- marketing/adr-0001-website-architecture.md | 107 ------------------ marketing/assets/README.md | 13 --- marketing/content-calendar.md | 87 -------------- marketing/social-profile-kit.md | 99 ---------------- 10 files changed, 693 deletions(-) delete mode 100644 docs/adr/0001-website-architecture.md delete mode 100644 docs/adr/0002-marketing-site-information-architecture.md delete mode 100644 docs/marketing/README.md delete mode 100644 docs/marketing/content-calendar-2026-q2.md delete mode 100644 docs/marketing/domain-shortlist-validation.md delete mode 100644 docs/marketing/social-profile-kit.md delete mode 100644 marketing/adr-0001-website-architecture.md delete mode 100644 marketing/assets/README.md delete mode 100644 marketing/content-calendar.md delete mode 100644 marketing/social-profile-kit.md diff --git a/docs/adr/0001-website-architecture.md b/docs/adr/0001-website-architecture.md deleted file mode 100644 index cf40266..0000000 --- a/docs/adr/0001-website-architecture.md +++ /dev/null @@ -1,85 +0,0 @@ -# ADR 0001: Website Architecture for Hype Marketing + Docs - -- **Status:** Draft -- **Date:** 2026-03-20 -- **Owners:** Gopher Guides / Hype maintainers - -## Context -Hype already has a live public site at `hypemd.dev` deployed via Dokploy. We need an architecture direction that supports: -- marketing pages and docs content -- fast iteration with low ops overhead -- straightforward CI/CD from GitHub -- SEO, social metadata, and reliability - -## Decision -Adopt a **Git-based static site workflow with Dokploy deployment** as the primary architecture. - -### Selected architecture -1. Source-controlled content + templates in the repo -2. Build artifact generation in CI -3. Dokploy-managed deploys to production -4. Canonical domain routing through `hypemd.dev` - -## Options considered -| Option | Summary | Pros | Cons | Decision | -|---|---|---|---|---| -| A. Static site + Dokploy (selected) | Build static assets from repo and deploy via Dokploy | Low ops burden, fast rollback, simple CI/CD | Limited dynamic features unless extra services added | **Chosen** | -| B. Dynamic app framework + managed DB | Use app runtime for docs + marketing | Flexible personalization/search | Higher maintenance, runtime incidents, more moving parts | Rejected for v1 | -| C. Third-party docs SaaS | Host docs externally and link marketing pages | Fast initial setup | Vendor lock-in, less control, fragmented brand | Rejected for v1 | - -## Rationale -- Existing live deployment already validates Dokploy as an execution path. -- Static output minimizes runtime complexity and operational risk. -- GitHub-driven flow aligns with contributor expectations and review process. -- Supports incremental improvement without framework migration churn. - -## Information architecture (v1) -- Home -- Docs -- Tutorials -- Blog -- Templates/Examples -- Changelog/Release notes - -## Deployment topology -- **Origin:** GitHub repository -- **Build:** CI workflow on push/merge to main -- **Deploy target:** Dokploy-managed service(s) -- **Domain:** `hypemd.dev` as canonical host -- **TLS:** managed at edge/reverse-proxy layer (Dokploy stack) - -## CI/CD outline -1. PR opened -> lint/test/build checks -2. Merge to main -> production build -3. Dokploy deploy hook/image update -4. Post-deploy smoke check (`/`, `/docs`, key assets) - -## Consequences -### Positive -- Low operational burden, fast publish cycle -- Easy rollback via Git commit history/deploy history -- Works with existing team workflows and infra - -### Negative / trade-offs -- Dynamic personalization/search depth may be limited without additional services -- Requires discipline in content structure and release process - -## Follow-up actions -- Document smoke test script for post-deploy verification -- Add architecture diagram to docs site operations page -- Define SLO for docs uptime + publish latency - -## Decision drivers -- Keep infra lightweight for a small maintainer team. -- Preserve content portability (avoid lock-in to a hosted docs vendor). -- Enable PR-first iteration where copy, code, and docs are reviewed together. - -## Non-goals (v1) -- Personalized per-user experiences. -- Custom search infra beyond baseline site search. -- Multi-region active/active runtime architecture. - -## Rollout plan -1. **Phase 1 (now):** stabilize IA + metadata + analytics tags. -2. **Phase 2:** add automated smoke tests + broken-link checks in CI. -3. **Phase 3:** evaluate optional managed search if docs volume materially grows. diff --git a/docs/adr/0002-marketing-site-information-architecture.md b/docs/adr/0002-marketing-site-information-architecture.md deleted file mode 100644 index 3c70692..0000000 --- a/docs/adr/0002-marketing-site-information-architecture.md +++ /dev/null @@ -1,95 +0,0 @@ -# ADR 0002: Marketing Site Information Architecture and Conversion Path - -- **Status:** Draft -- **Date:** 2026-03-20 -- **Owners:** Gopher Guides / Hype maintainers - -## Context -We need a website structure that supports both discoverability (SEO/social) and conversion (trial/usage) without introducing a heavy application runtime. - -Current state: -- Canonical domain: `hypemd.dev` -- Existing architecture direction: static-site workflow + Dokploy deployment (ADR 0001) - -Gap: -- No explicit decision on page hierarchy, conversion funnel, and content ownership boundaries. - -## Decision -Adopt a **docs-adjacent marketing IA** with explicit conversion path and reusable page templates. - -### v1 page architecture -1. **Home (`/`)** - - Value proposition - - Primary CTA: Quickstart - - Secondary CTA: GitHub repo -2. **Use Cases (`/use-cases`)** - - Team scenarios: docs teams, dev advocates, OSS maintainers -3. **Docs (`/docs`)** - - Reference + guides -4. **Blog (`/blog`)** - - Product updates, tutorials, and proof posts -5. **Examples (`/examples`)** - - Real snippets/templates and before/after artifacts -6. **Changelog (`/changelog`)** - - Release updates mapped to capability changes - -### IA tree (navigation) -- `/` - - `/use-cases` - - `/use-cases/docs-teams` - - `/use-cases/devrel` - - `/use-cases/oss-maintainers` - - `/docs` - - `/docs/quickstart` - - `/docs/cli-reference` - - `/blog` - - `/examples` - - `/changelog` - -### Conversion path -Social post / search result -> Home or Use Case page -> Quickstart -> Repository stars/issues/discussions - -## Options considered -| Option | Summary | Pros | Cons | Decision | -|---|---|---|---|---| -| A. Docs-adjacent marketing IA (selected) | Marketing pages and docs in one coherent structure | Shared templates, easier navigation, stronger SEO continuity | Requires editorial discipline | **Chosen** | -| B. Separate marketing microsite | Dedicated marketing site apart from docs | Design freedom for campaigns | Split ownership, duplicate content risk, SEO fragmentation | Rejected | -| C. Docs-only site with blog | Skip explicit marketing pages | Lowest effort initially | Weak narrative for first-time visitors; poorer conversion | Rejected | - -## Rationale -- Keeps maintenance low while improving message clarity. -- Allows iterative content work without architecture churn. -- Aligns with a small-team operating model and repo-first workflows. - -## Consequences -### Positive -- Clear discoverability and conversion path. -- Better editorial planning: each page type has explicit purpose. -- Reusable template system supports consistent branding. - -### Trade-offs -- Requires ongoing content governance to avoid stale pages. -- Initial setup effort for page scaffolding and templates. - -## Follow-up Actions -- [ ] Add route/page stubs for `/use-cases`, `/examples`, and `/changelog`. -- [ ] Define per-page metadata checklist (title, description, OG image, canonical). -- [ ] Add measurement plan (click-through to quickstart, docs depth, returning visitors). -- [ ] Add UTM governance doc for social and campaign links. - -## Measurement Plan (v1) -- **North-star conversion:** quickstart CTA click-through rate from home/use-cases pages. -- **Activation proxy:** unique visitors reaching `/docs/quickstart` within same session. -- **Retention proxy:** 7-day returning visitor ratio to docs/blog pages. -- **Channel attribution:** UTM-tagged social links for post-level performance. - -## Implementation Guardrails -- No SPA runtime requirement for v1 pages. -- Every marketing page must include canonical URL + OG metadata. -- New top-level pages require ADR update or ADR addendum. - -## Owner Mapping -- Marketing docs and calendars: `docs/marketing/*` -- Architecture decisions: `docs/adr/*` -- Brand assets: `assets/brand/*` -- Product documentation source of truth: `docs/*` diff --git a/docs/marketing/README.md b/docs/marketing/README.md deleted file mode 100644 index 1011ae3..0000000 --- a/docs/marketing/README.md +++ /dev/null @@ -1,6 +0,0 @@ -# Marketing Artifacts - -- [Domain shortlist validation and decision matrix](./domain-shortlist-validation.md) -- [Content calendar scaffold + first post drafts](./content-calendar-2026-q2.md) -- [Social profile kit draft](./social-profile-kit.md) -- [Website architecture ADR](../adr/0002-marketing-site-information-architecture.md) diff --git a/docs/marketing/content-calendar-2026-q2.md b/docs/marketing/content-calendar-2026-q2.md deleted file mode 100644 index 832ddf5..0000000 --- a/docs/marketing/content-calendar-2026-q2.md +++ /dev/null @@ -1,85 +0,0 @@ -# Hype Content Calendar Scaffold (Q2 2026) - -## Goals -- Grow awareness among Go developers, docs-first teams, and developer advocates. -- Convert interest into trial installs and docs visits. -- Build proof through practical demos and before/after docs examples. - -## Cadence -- **2 posts/week** on X + LinkedIn -- **1 technical blog post/week** on `hypemd.dev/blog` -- **1 demo artifact/week** (template, snippet pack, or short walkthrough) - -## Pillars -1. **Product Education** — how Hype works and where it saves time. -2. **Workflow Integrations** — CI, docs repos, blog pipelines, and developer tooling. -3. **Proof & Outcomes** — real examples, performance/reliability wins. -4. **Community** — user showcases, tips, and contribution opportunities. - -## Weekly Scaffold (first 4 weeks) -| Week (2026) | Product Education | Workflow Integrations | Proof & Outcomes | Community | -|---|---|---|---|---| -| W1 (Mar 23) | "What is Hype" explainer | GitHub Actions publish flow | Before/after docs quality comparison | Ask for examples from users | -| W2 (Mar 30) | Parser/CLI quick tips | Docs + blog in one repo | Build-time and error reporting walkthrough | Share template call for contributors | -| W3 (Apr 6) | Metadata + SEO support | Social card and OG automation | Traffic uplift case study format | Feature request spotlight | -| W4 (Apr 13) | Export/validation deep dive | Dokploy deployment guide | Reliability checklist post | Office-hours / AMA prompt | - -## Two Concrete Drafts (PR-ready) - -### Draft 01 — X + LinkedIn (Week 1, Tue Mar 24) -- **Goal:** Introduce core problem/solution with a clear CTA. -- **Primary CTA:** `https://hypemd.dev/?utm_source=social&utm_medium=x&utm_campaign=q2_w1_intro` -- **Secondary CTA:** `https://github.com/gopherguides/hype?utm_source=social&utm_medium=linkedin&utm_campaign=q2_w1_intro` -- **Asset:** quickstart screenshot (`assets/marketing/q2-w1-intro.png`) - -**X version (<=280 chars)** -Docs and blogs shouldn’t require 2+ pipelines and glue scripts. - -Hype keeps publishing markdown-native in one workflow: -• docs + blog from one repo -• pre-deploy validation -• cleaner SEO/social metadata - -Start: https://hypemd.dev/?utm_source=social&utm_medium=x&utm_campaign=q2_w1_intro - -**LinkedIn version** -Many teams pay a hidden tax by splitting docs and blog pipelines. - -Hype keeps publishing markdown-native so teams can: -- ship docs + blog from one repo -- validate links/content before deployment -- publish cleaner metadata for SEO and social cards - -Start: https://hypemd.dev/?utm_source=social&utm_medium=linkedin&utm_campaign=q2_w1_intro -Repo: https://github.com/gopherguides/hype?utm_source=social&utm_medium=linkedin&utm_campaign=q2_w1_intro - -### Draft 02 — X + LinkedIn (Week 1, Thu Mar 26) -- **Goal:** Position reliability + low-ops value for small teams. -- **Primary CTA:** Drive replies via concrete question. -- **Asset:** validation output screenshot (`assets/marketing/q2-w1-reliability.png`) - -**X version (<=280 chars)** -Small docs teams don’t need more tooling—they need fewer failure points. - -Hype focuses on boring reliability: -• markdown-native authoring -• deterministic build/export paths -• low-ops deployment patterns - -What would you automate first: validation, metadata, or deploy checks? - -**LinkedIn version** -Most docs incidents come from pipeline complexity, not writing quality. - -Hype reduces operational drag with: -- markdown-native authoring -- deterministic export/build behavior -- lightweight deployment patterns - -For your docs workflow, what would you automate first: validation, metadata, or deploy checks? - -## Publishing Ops Checklist -- [ ] Create `assets/marketing/q2-w1-intro.png` and `assets/marketing/q2-w1-reliability.png`. -- [ ] Add first-week posts to scheduler with local timezone (America/Chicago). -- [ ] Create matching W1 technical blog draft with same UTM campaign tags. -- [ ] Capture baseline metrics (profile visits, link clicks, repo stars) before publishing. diff --git a/docs/marketing/domain-shortlist-validation.md b/docs/marketing/domain-shortlist-validation.md deleted file mode 100644 index 8379df3..0000000 --- a/docs/marketing/domain-shortlist-validation.md +++ /dev/null @@ -1,54 +0,0 @@ -# Hype Domain Shortlist Validation (2026-03-20) - -## Objective -Select a primary marketing domain and two defensive registrations for the Hype project. - -## Decision Matrix -Scoring: 1 (poor) to 5 (excellent). Weighted total = score × weight. - -| Criteria | Weight | hype.sh | hypemd.dev | hype.run | hypecli.dev | hypemd.run | usehype.dev | -|---|---:|---:|---:|---:|---:|---:|---:| -| Brand clarity (Hype markdown tooling) | 5 | 3 | 5 | 3 | 4 | 5 | 4 | -| Memorability | 4 | 5 | 4 | 4 | 3 | 3 | 4 | -| Developer trust / credibility | 4 | 3 | 5 | 4 | 4 | 4 | 4 | -| SEO keyword relevance | 3 | 2 | 5 | 2 | 4 | 4 | 3 | -| Expansion flexibility | 2 | 4 | 4 | 4 | 3 | 4 | 4 | -| Typo/confusion risk | 3 | 3 | 4 | 3 | 4 | 4 | 3 | -| **Weighted total** | | **53** | **85** | **58** | **67** | **73** | **69** | - -## Validation Notes - -### DNS/Resolution Snapshot (2026-03-21 UTC) - -| Domain | Resolves now? | Notes | -|---|---|---| -| `hypemd.dev` | Yes (`129.212.149.192`) | Confirms active domain in use. | -| `hypecli.dev` | No A/CNAME observed | Candidate appears unconfigured; verify registrar availability. | -| `hype.run` | Yes (`76.223.54.146`, `13.248.169.48`) | Already registered by third party; not suitable for near-term launch plan. | -| `hype.sh` | Yes (`217.92.164.52`) | Registered/active by third party; not practical as primary. | -| `hypemd.run` | No A/CNAME observed | Strong fallback candidate for redirects/campaign links. | -| `usehype.dev` | No A/CNAME observed | Good fallback if `hypecli.dev` unavailable. | - -## Decision (current) -1. **Primary canonical:** `hypemd.dev` -2. **Defensive target #1:** `hypecli.dev` -3. **Defensive target #2 fallback order:** `hypemd.run`, then `usehype.dev` - -## Recommendation -1. Keep `hypemd.dev` as canonical primary domain. -2. Prioritize acquisition attempt for `hypecli.dev`. -3. Replace `hype.run` defensive slot with likely-available fallback (`hypemd.run` then `usehype.dev`). -4. Route all alternates to canonical URLs with 301 redirects to consolidate SEO authority. - -## Implementation Checklist -- [ ] Verify registrar availability + pricing for `hypecli.dev`, `hypemd.run`, and `usehype.dev`. -- [ ] Register first available fallback set and enable registrar lock. -- [ ] Add DNS + TLS config in Dokploy/edge layer. -- [ ] Configure 301 redirects to canonical `https://hypemd.dev` routes. -- [ ] Add canonical tags and update sitemap host references. -- [ ] Add domain ownership + renewal reminder to ops checklist. - -## Issue Update Snippet (for #83) -- Decision matrix expanded with fallback candidates and weighted scoring. -- Primary remains `hypemd.dev`; defensive priority is now `hypecli.dev` then `hypemd.run`. -- `hype.run` and `hype.sh` remain occupied and are removed from launch-critical path. diff --git a/docs/marketing/social-profile-kit.md b/docs/marketing/social-profile-kit.md deleted file mode 100644 index 0251f20..0000000 --- a/docs/marketing/social-profile-kit.md +++ /dev/null @@ -1,62 +0,0 @@ -# Hype Social Profile Kit (Draft v2) - -## Brand Positioning (one-liner) -Hype is a markdown-native publishing toolchain for docs and blogs with a low-ops deployment path. - -## Profile Handle Strategy -- Preferred: `@hypemd` -- Fallback 1: `@hypemddev` -- Fallback 2: `@hypecli` - -## Platform Bios - -### X / Twitter (160 chars) -Markdown-native docs + blog publishing for developer teams. Build, validate, and ship from one workflow. https://hypemd.dev - -### LinkedIn (220 chars) -Hype helps developer teams publish docs and blogs from a single markdown-driven workflow. Fewer moving parts, better metadata, and practical deployment paths. - -### GitHub Org/Repo short description -Markdown-native docs and blog tooling for fast, low-ops publishing. - -## Pinned Post / Intro Template -We build Hype for teams that want docs + blog publishing without a fragile stack. - -Follow for: -- practical markdown workflows -- deployment playbooks -- examples and templates - -Start: https://hypemd.dev - -## Visual Kit Checklist -- [ ] Avatar: simple Hype logomark (readable at 48×48) -- [ ] Header image: value prop + URL (`hypemd.dev`) -- [ ] Link-in-bio: docs, quickstart, repo, examples -- [ ] Branded card template for feature announcements - -## Voice + Style Guardrails -- Tone: practical, confident, no hype-y fluff. -- Keep posts short, specific, and actionable. -- Prefer examples over claims. -- Avoid punching down at competing tools. - -## CTA Library -- "Start with the quickstart: https://hypemd.dev" -- "See the repo: https://github.com/gopherguides/hype" -- "Tell us your docs pain point; we’ll build a walkthrough." - -## Launch-Day Profile Setup Checklist (Concrete) -1. Reserve final handle (`@hypemd` preferred) across X + LinkedIn. -2. Update bios to final copy above. -3. Upload `assets/brand/twitter-avatar.png` and `assets/brand/twitter-header.png`. -4. Publish pinned intro post and include quickstart URL. -5. Add first two scheduled posts from `docs/marketing/content-calendar-2026-q2.md`. -6. Verify profile links resolve to canonical `https://hypemd.dev`. - -## Ready-to-copy Profile Fields -- **Display name:** Hype -- **Category:** Software / Developer Tools -- **Location:** Remote -- **Website:** https://hypemd.dev -- **Contact:** hello@hypemd.dev (placeholder until team alias is finalized) diff --git a/marketing/adr-0001-website-architecture.md b/marketing/adr-0001-website-architecture.md deleted file mode 100644 index e6d8094..0000000 --- a/marketing/adr-0001-website-architecture.md +++ /dev/null @@ -1,107 +0,0 @@ -# ADR 0001: Website Architecture for Hype Docs + Marketing - -- **Status:** Proposed -- **Date:** 2026-03-20 -- **Owners:** Hype maintainers -- **Related issue:** https://github.com/gopherguides/hype/issues/84 - -## Context - -Hype needs a website architecture that supports two jobs without splitting the user journey: - -1. **Marketing narrative** (what Hype is, why it matters, social proof, CTAs) -2. **Technical docs** (quickstart, command reference, examples) - -Current constraints: -- Team bandwidth is limited; architecture should be simple to operate. -- Content velocity matters more than custom frontend complexity. -- Website should reinforce Hype itself as the engine (dogfooding). -- We want low hosting cost, fast page loads, and straightforward deploys. - -## Decision drivers - -1. Keep build/deploy system maintainable by a small team. -2. Optimize for content publishing speed (not bespoke web app development). -3. Keep docs and marketing in one information architecture. -4. Preserve future optionality for richer docs/search. -5. Favor static hosting + CDN for reliability and cost. - -## Considered options - -### Option A — Hype-generated static site (single repo) on DigitalOcean Static Sites -- Use Hype as primary generator for docs + lightweight marketing pages. -- Deploy static artifacts to DigitalOcean-managed static hosting/CDN. - -### Option B — Hugo/Astro marketing site + separate docs stack -- Split responsibilities: modern framework for marketing, separate docs pipeline. -- Potentially better design flexibility, but higher cognitive load. - -### Option C — Fully custom web app (Next.js) with dynamic content pipeline -- Maximum flexibility and integrations. -- Highest ops complexity and maintenance burden. - -## Decision matrix - -Scoring scale: 1 (weak) to 5 (strong) - -| Criterion | Weight | A: Hype + DO Static | B: Split stack | C: Custom app | -|---|---:|---:|---:|---:| -| Team maintainability | 30% | 5 | 3 | 2 | -| Publishing velocity | 25% | 5 | 3 | 2 | -| Cost + ops simplicity | 20% | 5 | 3 | 2 | -| UX/design flexibility | 15% | 3 | 4 | 5 | -| Long-term extensibility | 10% | 4 | 4 | 5 | -| **Weighted total (/5)** | | **4.60** | **3.20** | **2.60** | - -## Decision - -Adopt **Option A**: Hype-generated unified static site deployed to DigitalOcean Static Sites. - -### Rationale - -- Fastest route to consistent docs + marketing publishing. -- Lowest operational burden for current team size. -- Strong product signal: Hype powers its own public content. -- Keeps future migration path open if richer app behavior becomes necessary. - -## Consequences - -### Positive -- Single content workflow and fewer moving parts. -- Lower hosting and maintenance overhead. -- Easy rollback model via static deploys. - -### Trade-offs / risks -- Less out-of-the-box interactivity than framework-heavy sites. -- Search and analytics integrations may need incremental additions. -- Design system sophistication depends on internal template investment. - -## Guardrails + follow-up tasks - -1. Define site IA v1: Home, Docs, Examples, Blog, Changelog. -2. Add deploy checklist (build, link check, smoke test, publish). -3. Define baseline analytics events (CTA clicks, docs entry points, quickstart conversions). -4. Revisit architecture after 90 days or at >50k monthly sessions. - -## Rollout plan (v1) - -- Week 1: finalize IA + templates for core pages. -- Week 2: migrate key docs/quickstart pages to unified nav. -- Week 3: connect analytics + publish content cadence from marketing calendar. -- Week 4: review metrics and backlog improvements. - -## v1 information architecture (concrete) -- `/` Home (value proposition + primary CTA to quickstart) -- `/docs` Documentation hub -- `/docs/quickstart` First successful run path -- `/examples` Executable examples gallery -- `/blog` Narrative + release posts -- `/changelog` Product updates and release notes - -## Measurement baseline (must-implement) -| Event | Trigger | Why it matters | -|---|---|---| -| `cta_quickstart_click` | Click from `/` to `/docs/quickstart` | Measures marketing -> docs conversion | -| `quickstart_copy_command` | Copy action on first command block | Measures trial intent | -| `repo_click` | Click to GitHub repo | Measures OSS contribution funnel | -| `docs_search_used` | First search interaction (when enabled) | Signals docs discoverability gaps | diff --git a/marketing/assets/README.md b/marketing/assets/README.md deleted file mode 100644 index c503c7e..0000000 --- a/marketing/assets/README.md +++ /dev/null @@ -1,13 +0,0 @@ -# Marketing Assets Queue - -This folder tracks required visual assets referenced by `marketing/content-calendar.md`. - -## Required for launch window -- `post-01-docs-drift.png` — side-by-side stale docs vs CI validation failure -- `post-02-include-reuse.png` — include reuse architecture diagram - -## Export specs -- Resolution: 1600x900 -- Format: PNG -- Keep text legible at mobile crop (center-safe) -- Store source files in `/tmp` or design tool; only final export lands here diff --git a/marketing/content-calendar.md b/marketing/content-calendar.md deleted file mode 100644 index 22d692d..0000000 --- a/marketing/content-calendar.md +++ /dev/null @@ -1,87 +0,0 @@ -# Hype Content Calendar Scaffold (Q2 2026) - -## Objectives -- Build awareness for Hype as executable docs tooling. -- Convert interest to GitHub stars, docs usage, and social follows. -- Establish repeatable weekly posting rhythm. - -## Cadence (starter) -- **Mon:** Problem/pain post (docs drift, broken samples) -- **Wed:** Product workflow/tutorial post -- **Fri:** Social proof/release/highlight post - -## Core themes -1. Docs-as-code reliability -2. Reusable content architecture -3. Validation in CI -4. Authoring speed and maintainability - -## 6-week scaffold - -| Week | Monday (problem) | Wednesday (how-to) | Friday (proof/update) | CTA | -|---|---|---|---|---| -| W1 | Why docs drift happens | Validate docs in CI with `hype export` | Before/after broken example save | Star repo + try quickstart | -| W2 | Copy/paste debt across docs | Reuse snippets with `` | Show reduced update effort | Read docs | -| W3 | Broken workshop moments | Use executable snippets with `` | Team workflow screenshot/demo | Follow X account | -| W4 | Static site limits for dev docs | Build blog with `hype blog build` | Theme + SEO highlight | Visit hypemd.dev | -| W5 | Onboarding friction from stale READMEs | Fast preview loop with `hype preview` | New user quote/community mention | Open issue / feedback | -| W6 | Hidden maintenance cost in docs | Multi-format output workflow | Monthly recap + roadmap teaser | Subscribe / contribute | - -## Launch window schedule (first 2 weeks) -| Date (CT) | Slot | Post | Channel(s) | Owner | Asset needed | -|---|---|---|---|---|---| -| 2026-03-23 | 9:00 AM | Post 01 — Docs Drift | X + LinkedIn | Hype maintainer | drift screenshot | -| 2026-03-25 | 11:30 AM | Post 02 — Include Reuse | X + LinkedIn | Hype maintainer | include flow diagram | -| 2026-03-27 | 12:00 PM | W1 proof/update | X | Hype maintainer | quick metric tile | -| 2026-03-30 | 9:00 AM | W2 problem post | X + LinkedIn | Hype maintainer | carousel/quote card | -| 2026-04-01 | 11:30 AM | W2 how-to post | X + LinkedIn | Hype maintainer | CLI demo GIF | -| 2026-04-03 | 12:00 PM | W2 proof/update | X | Hype maintainer | snippet screenshot | - -## Publishing checklist (repeatable) -1. Add UTM-tagged primary link (`?utm_source=&utm_medium=social&utm_campaign=q2_launch`). -2. Validate command snippets against current `main` before posting. -3. Include alt text for every image/GIF. -4. Reply-ready first comment prepared (docs link + quickstart). -5. Capture post URL + engagement after 24h. - -## Drafts produced -- `marketing/posts/post-01-docs-drift.md` -- `marketing/posts/post-02-include-reuse.md` - -## Production readiness checklist (Posts 01-02) -| Item | Post 01 | Post 02 | Status | -|---|---|---|---| -| Copy finalized for X + LinkedIn | ✅ | ✅ | Ready | -| UTM links validated | ✅ | ✅ | Ready | -| First comment/reply seed prepared | ✅ | ✅ | Ready | -| Creative brief + alt text specified | ✅ | ✅ | Needs asset creation | -| Publish slot assigned (CT) | 2026-03-23 9:00 AM | 2026-03-25 11:30 AM | Scheduled | - -## Metrics capture scaffold -- Track at +24h and +7d for each post: - - impressions - - engagements - - profile visits - - link clicks - - net new GitHub stars (daily delta) - -## Concrete production briefs for first two posts - -### Post 01 asset brief (Docs Drift) -- Format: 1600x900 PNG -- Frame A: stale snippet shown in docs page -- Frame B: CI failure output from executable snippet validation -- Overlay text: "Catch docs drift in CI" -- Alt text owner: marketing maintainer -- Done definition: image committed at `marketing/assets/post-01-docs-drift.png` - -### Post 02 asset brief (Include Reuse) -- Format: 1600x900 PNG -- Diagram: one canonical snippet -> README + docs + tutorial -- Overlay text: "Write once, reuse everywhere" -- Alt text owner: marketing maintainer -- Done definition: image committed at `marketing/assets/post-02-include-reuse.png` - -## Suggested issue mapping -- Positioning + narrative thread: https://github.com/gopherguides/hype/issues/82 -- Social execution thread: https://github.com/gopherguides/hype/issues/85 diff --git a/marketing/social-profile-kit.md b/marketing/social-profile-kit.md deleted file mode 100644 index d76d7d4..0000000 --- a/marketing/social-profile-kit.md +++ /dev/null @@ -1,99 +0,0 @@ -# Hype Social Profile Kit (Draft) - -## Primary account -- X/Twitter: https://x.com/hype_markdown -- Website: https://hypemd.dev -- Repo: https://github.com/gopherguides/hype - -## Bio options - -### Option A (default) -Executable docs for developers. -Run and validate code samples in Markdown so docs stay accurate. -Open source by @gopherguides. - -### Option B (short) -Markdown docs that run real code. -Validation built in. Docs never drift. -OSS by @gopherguides. - -### Option C (technical) -Docs-as-code tooling with executable snippets, includes, and validation. -Build reliable dev docs with Hype. - -## Profile naming -- Display name: `Hype (Markdown Docs)` -- Handle: `@hype_markdown` (already live) - -## Link strategy -- Primary link in profile: `https://hypemd.dev` -- Secondary links to rotate in posts: - - `https://hypemd.dev/docs` - - `https://github.com/gopherguides/hype` - -## Pinned post template -Hype is an open-source Markdown content generator that executes and validates code examples. - -If docs matter to your product, they should be testable. - -✅ Executable snippets -✅ Reusable includes -✅ Validation for docs in CI - -Start: https://hypemd.dev -Repo: https://github.com/gopherguides/hype - -## Asset checklist (profile completeness) -- Avatar: high-contrast Hype logo (square, readable at 48x48). -- Header image: “Executable Markdown docs” tagline + URL. -- Location: optional (`Remote`). -- Pinned post: publish from template above. -- Accessibility: image alt text included on each visual post. - -## Voice/tone guardrails -- Practical, technical, no hype language. -- Prefer concrete examples over claims. -- Keep posts concise and useful. -- Avoid dunking on competing tools; compare by capability. - -## Hashtag starter set -- Primary: `#Documentation #DocsAsCode #DevTools #Golang` -- Optional rotation: `#DeveloperExperience #OpenSource` - -## Response playbook (lightweight) -- **Question about setup:** reply with quickstart link + one command. -- **Feature request:** acknowledge + open/point to GitHub issue. -- **Bug report:** ask for repro snippet + environment. -- **Praise/mentions:** thank and ask what workflow they’re using. - -## 7-day launch micro-plan -1. Day 1: refresh profile bio + header + pinned post. -2. Day 2: publish Post 01 (docs drift). -3. Day 4: publish Post 02 (include reuse). -4. Day 5: reply to all comments/mentions with docs links where relevant. -5. Day 7: recap post with one measurable outcome (clicks, stars, follows). - -## Channel field map (fill once, reuse quarterly) -| Field | X/Twitter value | LinkedIn page value | -|---|---|---| -| Name | Hype (Markdown Docs) | Hype by Gopher Guides | -| Tagline | Executable docs for developers | Reliable docs-as-code with executable snippets | -| Website | https://hypemd.dev | https://hypemd.dev | -| CTA link | https://hypemd.dev/docs | https://github.com/gopherguides/hype | - -## Launch week operating rhythm -- Daily (Mon-Fri): 15-minute mention/reply triage window. -- Twice weekly: capture FAQ patterns and convert one into post/comment copy. -- Friday: update pinned reply with latest docs/quickstart link if changed. - -## Day-1 profile setup checklist (execution order) -1. Update display name and bio (Option A default). -2. Set profile URL to `https://hypemd.dev`. -3. Upload avatar + header and verify mobile crop. -4. Publish pinned post from template in this doc. -5. Reply to pinned post with quickstart link (`https://hypemd.dev/docs`). -6. Capture profile screenshot for changelog/archive. - -## Suggested issue mapping -- Primary update target: https://github.com/gopherguides/hype/issues/85 -- Cross-reference content cadence decisions: https://github.com/gopherguides/hype/issues/82 From 0ec08c4041055f1dfc7bf0d839a1a0121c0f3986 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Sat, 21 Mar 2026 03:43:17 +0000 Subject: [PATCH 14/14] Update README.md with latest Hype changes --- README.md | 10 +--------- 1 file changed, 1 insertion(+), 9 deletions(-) diff --git a/README.md b/README.md index 19c128d..ebd471c 100644 --- a/README.md +++ b/README.md @@ -1726,9 +1726,6 @@ Here is the current structure that we are using to create this readme: $ tree ./docs ./docs -├── adr -│   ├── 0001-website-architecture.md -│   └── 0002-marketing-site-information-architecture.md ├── badges.md ├── blog │   ├── README.md @@ -1748,11 +1745,6 @@ $ tree ./docs ├── installation.md ├── license.md ├── marked.md -├── marketing -│   ├── README.md -│   ├── content-calendar-2026-q2.md -│   ├── domain-shortlist-validation.md -│   └── social-profile-kit.md ├── mermaid.md ├── preview.md ├── quick-reference.md @@ -1766,7 +1758,7 @@ $ tree ./docs │   └── main.go └── slides.md -10 directories, 30 files +8 directories, 24 files ``` ---