feat/update-default-published-state #2009
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,312 @@ | ||
| --- | ||
| display_title: "Choosing a CMS in 2025: A Guide for Technical Teams" | ||
| meta_title: "Choosing a CMS: Sanity vs Payload vs GitHub vs Keystatic" | ||
| meta_description: "A deep guide to choosing a CMS in 2025. Compare Git-based CMS, headless CMS like Sanity and Payload, Nextra-style frameworks, GitBook, and when you shouldn’t use a CMS at all." | ||
| author: "John Jeong" | ||
| created: "2025-11-28" | ||
| coverImage: "https://hyprnote.com/og/choosing-a-cms.png" | ||
| published: true | ||
| --- | ||
|
|
||
| # Choosing a CMS in 2025: A Guide for Technical Teams | ||
|
|
||
| If you’re building a blog, docs, or a knowledge base in 2025, the options are… overwhelming. | ||
|
|
||
| Sanity or Payload? | ||
| Nextra or GitBook? | ||
| Git-based CMS like Keystatic? | ||
| Or just raw MDX in GitHub with zero CMS at all? | ||
|
|
||
| We went through the same decision for Hyprnote. | ||
| This post is my attempt to **map the territory** so you don’t have to burn as many cycles. | ||
|
|
||
| I’m not going to tell you “X is the best CMS.” | ||
| I’ll show you **what each category is good at**, what it quietly locks you into, and when you probably don’t need a CMS at all. | ||
|
|
||
| This is Part 3 in our publishing series: | ||
|
|
||
| - Part 1 – *Why We Write Our Blog in an IDE* | ||
| - Part 2 – *Why Our CMS Is GitHub* | ||
| - Part 3 – *This post: how to choose a CMS in 2025* | ||
|
|
||
| --- | ||
|
|
||
| ## Step 0: Decide What Problem You’re Actually Solving | ||
|
|
||
| “Which CMS should we use?” is the wrong first question. | ||
|
|
||
| Better questions: | ||
|
|
||
| 1. **Who is writing most of the content?** | ||
| - engineers only | ||
| - mixed team (engineers + PMs + marketing) | ||
| - non-technical people only | ||
|
|
||
| 2. **What are you publishing?** | ||
| - technical blog | ||
| - product docs / API reference | ||
| - internal knowledge base | ||
| - marketing pages / landing pages | ||
|
|
||
| 3. **How often does content structure change?** | ||
| - almost never (simple posts, titles, tags) | ||
| - sometimes (new fields, types, locales) | ||
| - constantly (complex content models, multiple channels) | ||
|
|
||
| 4. **How long should your content survive?** | ||
| - 6 months? | ||
| - 2–3 years? | ||
| - 10+ years and multiple stack rewrites? | ||
|
|
||
| Once you answer these, the CMS choice mostly falls out. | ||
|
|
||
| --- | ||
|
|
||
| ## The Four Big Buckets of CMS Options | ||
|
|
||
| Let’s define the buckets first: | ||
|
|
||
| 1. **No CMS, just Git + MDX** | ||
| 2. **Git-based CMS (visual UI on top of your repo)** | ||
| 3. **Headless CMS (API-first like Sanity, Payload)** | ||
| 4. **Hosted doc/knowledge platforms (GitBook, Notion, etc.)** | ||
|
|
||
| We’ll walk through each, then I’ll give you a “when to pick which” section. | ||
|
|
||
| --- | ||
|
|
||
| ## 1. No CMS: Just Git + MDX (What We Use) | ||
|
|
||
| This is what we do at Hyprnote: | ||
|
|
||
| - content lives as `.mdx` files in the repo | ||
| - we write in Zed / Cursor / VS Code | ||
| - GitHub is the CMS | ||
| - PRs are drafts, merges are publish | ||
| - CI handles link checking, OG generation, etc. | ||
|
|
||
| Pros: | ||
|
|
||
| - maximum **portability** (plain files last decades) | ||
| - works perfectly with modern frameworks (Next.js, TanStack Start, Astro) via MDX support [oai_citation:0‡Next.js](https://nextjs.org/docs/pages/guides/mdx?utm_source=chatgpt.com) | ||
|
Contributor
There was a problem hiding this comment. 🧩 Analysis chain🏁 Script executed: # First, check if file exists and its size
wc -l apps/web/content/articles/choosing-a-cms.mdxRepository: fastrepl/hyprnote Length of output: 109 🏁 Script executed: # Find all oai_citation markers with line numbers
rg -n 'oai_citation' apps/web/content/articles/choosing-a-cms.mdxRepository: fastrepl/hyprnote Length of output: 3684 Remove web search citation artifacts before publishing. This file contains 18 Found at lines: 91, 110, 112, 139, 145, 146, 153, 156, 157, 164, 184, 190, 199, 215, 294, 296, 298. Examples: Remove all 🤖 Prompt for AI Agents |
||
| - diffable, reviewable, scriptable | ||
| - no vendor lock-in, no schema migrations | ||
| - ideal if your writers are engineers | ||
|
|
||
| Cons: | ||
|
|
||
| - non-technical teammates need training or another surface | ||
| - no drag-and-drop media UI out of the box | ||
| - no built-in content dashboard, workflows, or roles | ||
|
|
||
| If your team is very technical and you’re early-stage, this is almost always the correct default. You can always add a Git-based or headless CMS later without throwing anything away. | ||
|
|
||
| --- | ||
|
|
||
| ## 2. Git-Based CMS: “UI for Your Repo” (Keystatic & Friends) | ||
|
|
||
| Git-based CMS tools give you a **visual editor that talks directly to your Git repo**. Your content is still Markdown/MDX/JSON/YAML in the repository, but non-technical people get a web UI. | ||
|
|
||
| **Keystatic** is a good example of the modern version of this: it makes Markdown, JSON, and YAML content in your codebase editable via a browser UI, and syncs changes directly to GitHub or the local file system, without introducing a separate database. [oai_citation:1‡Keystatic](https://keystatic.com/?utm_source=chatgpt.com) | ||
|
|
||
| Other players in this space include TinaCMS, Decap, etc., which a lot of devs compare as “Git-based CMS for React/Next.” [oai_citation:2‡DEV Community](https://dev.to/linkb15/top-5-git-based-cms-comparison-as-of-april-2024-4k1e?utm_source=chatgpt.com) | ||
|
|
||
| Pros: | ||
|
|
||
| - fits the **“content as code”** philosophy | ||
| - you keep all the benefits of Git (history, branches, PRs) | ||
| - non-engineers get a UI to edit content safely | ||
| - still portable (files in Git), no proprietary content lake | ||
| - good fit for Next.js / Remix / Astro setups | ||
|
|
||
| Cons: | ||
|
|
||
| - another admin app to host/configure | ||
| - the UI still has limits vs raw MDX | ||
| - you’re tied into their config models and upgrade cycle | ||
| - not as “enterprise omnichannel” as big headless CMSs | ||
|
|
||
| When to use this: | ||
|
|
||
| > You like our Git + MDX approach, but you want PMs / designers / marketing to be able to tweak copy and metadata without opening an IDE. | ||
| --- | ||
|
|
||
| ## 3. Headless CMS: Sanity, Payload, and the Heavy Hitters | ||
|
|
||
| Headless CMS = content backend with APIs. Frontend is up to you. | ||
|
|
||
| You define schemas, models, relationships, and the CMS exposes content via REST/GraphQL/other APIs to web, mobile, native apps, signage, whatever. [oai_citation:3‡Sanity.io](https://www.sanity.io/headless-cms?utm_source=chatgpt.com) | ||
|
|
||
| ### Sanity | ||
|
|
||
| Sanity is one of the big names here: | ||
|
|
||
| - it offers a composable “Content Cloud” with an open-source Studio built in React/TypeScript, highly customizable, and aimed at flexible content modeling. [oai_citation:4‡Sanity.io](https://www.sanity.io/?utm_source=chatgpt.com) | ||
| - content is stored in their **Content Lake** as structured JSON, not HTML, so you can reuse it across multiple frontends. [oai_citation:5‡Pagepro](https://pagepro.co/blog/what-is-sanity/?utm_source=chatgpt.com) | ||
| - it provides real-time collaboration, visual editing, and omnichannel delivery. | ||
|
|
||
| This is great when you have multiple frontends, lots of content types, and non-technical editors who need good UX. | ||
|
|
||
| ### Payload | ||
|
|
||
| Payload is a dev-first, code-first headless CMS built with Node.js, TypeScript and React, positioning itself as a Next.js-native backend framework. [oai_citation:6‡Payload](https://payloadcms.com/?utm_source=chatgpt.com) | ||
|
|
||
| - you configure everything in TypeScript | ||
| - it’s open-source (MIT), self-hostable, and can double as a headless CMS, app framework, or digital asset management layer. [oai_citation:7‡GitHub](https://github.com/payloadcms/payload?utm_source=chatgpt.com) | ||
| - it fits naturally into a modern JS/TS stack with Next.js-based projects. [oai_citation:8‡Payload](https://payloadcms.com/docs/getting-started/what-is-payload?utm_source=chatgpt.com) | ||
|
|
||
| Pros of headless CMS: | ||
|
|
||
| - powerful **schema & content modeling** | ||
| - omnichannel delivery (web, mobile, internal tools) | ||
| - good editorial UIs, roles, workflows | ||
| - often built-in localization, scheduling, etc. [oai_citation:9‡Sanity.io](https://www.sanity.io/headless-cms?utm_source=chatgpt.com) | ||
|
|
||
| Cons: | ||
|
|
||
| - more infra complexity (hosting, API auth, migrations) | ||
| - content now lives in a **proprietary structure** (export is possible, but not as simple as copying MDX files) | ||
| - your team must think in terms of “schemas” and “content models,” not just “posts” | ||
|
|
||
| When to use this: | ||
|
|
||
| > You’re not just running a blog. You’re running a **content platform** with multiple surfaces, locales, and non-technical editors who need structured workflows. | ||
| --- | ||
|
|
||
| ## 4. Docs / Knowledge Platforms: GitBook, Notion & Co. | ||
|
|
||
| Sometimes you don’t need a CMS. You need a **docs product**. | ||
|
|
||
| ### GitBook | ||
|
|
||
| GitBook positions itself as a documentation + knowledge base platform for technical teams, with a polished block-based editor, site customization options, and Git Sync that lets you connect to GitHub/GitLab for a docs-as-code workflow. [oai_citation:10‡GitBook](https://gitbook.com/docs?utm_source=chatgpt.com) | ||
|
|
||
| It’s very good if you want: | ||
|
|
||
| - a hosted, beautiful docs site | ||
| - search, navigation, versioning, and collaboration | ||
| - optional Git synchronization for teams that still want Markdown in repos [oai_citation:11‡GitBook](https://gitbook.com/docs/guides/docs-best-practices/documentation-structure-tips?utm_source=chatgpt.com) | ||
|
|
||
| Notion, Confluence, etc. live in the same general category (less dev-focused, more general knowledge management). | ||
|
|
||
| Pros: | ||
|
|
||
| - **fastest path** to a nice-looking docs/knowledge base | ||
| - low setup cost, almost no infra | ||
| - very friendly for non-tech stakeholders | ||
| - often have built-in AI-assisted search/summary now [oai_citation:12‡GitBook](https://www.gitbook.com/?utm_source=chatgpt.com) | ||
|
|
||
| Cons: | ||
|
|
||
| - content portability is limited (exports often messy) | ||
| - integrating tightly into your product site can be harder | ||
| - you’re living inside someone else’s product roadmap | ||
|
|
||
| When to use this: | ||
|
|
||
| > You want a **docs site tomorrow**, UX matters more than control, and you don’t mind long-term platform dependency. | ||
| --- | ||
|
|
||
| ## 5. Special Case: Nextra & Friends (Frameworks, Not CMSs) | ||
|
|
||
| Tools like **Nextra** are not CMS platforms, but content-focused frameworks built on Next.js that make it easy to build docs/blog sites with Markdown/MDX and opinionated themes. [oai_citation:13‡Nextra](https://nextra.site/docs?utm_source=chatgpt.com) | ||
|
|
||
| Think of Nextra as: | ||
|
|
||
| - prebuilt docs/blog UI (sidebar, nav, search glue) | ||
| - MDX-first authoring | ||
| - great for developer docs & personal blogs | ||
|
|
||
| You still choose how to manage content (just files, Git-based CMS, headless CMS feeding MDX remotely, etc.). | ||
|
|
||
| This is the category Hyprnote’s stack rhymes with: modern React/MDX front-end, but content-first in Git. | ||
|
|
||
| --- | ||
|
|
||
| ## A Simple Decision Matrix (So You Don’t Overthink It) | ||
|
|
||
| You can ignore everything above and just use this: | ||
|
|
||
| | Situation | Likely Best Choice | | ||
| |----------|--------------------| | ||
| | Small, technical team, mostly engineers writing | **Git + MDX, no CMS** | | ||
| | Technical team, but PMs/design/marketing need to edit copy | **Git-based CMS** (Keystatic/Tina/etc.) | | ||
| | Product needs content across web, app, marketing, multiple locales | **Headless CMS** (Sanity, Payload, etc.) | | ||
| | You just need a docs/KB site ASAP | **Docs platform** (GitBook, maybe Notion early) | | ||
| | You want fine control over UI + MDX, but not heavy infra | **Nextra or similar framework** on top of Git | | ||
|
|
||
| If you’re not sure, default to: | ||
|
|
||
| > **Git + MDX now. | ||
| > Add a Git-based or headless CMS later _if_ reality forces you to.** | ||
| Most teams overestimate how much “CMS” they need for the first 2–3 years. | ||
|
|
||
| --- | ||
|
|
||
| ## Things People Don’t Talk About Enough | ||
|
|
||
| A few non-obvious things we learned while thinking about this for Hyprnote: | ||
|
|
||
| ### 1. Lock-in doesn’t hurt until you’re tired and busy | ||
|
|
||
| Headless CMS and hosted doc platforms feel great in the first year. Export and migration problems show up **right when you least want to deal with them**: when the product is working and you’re stretched thin. | ||
|
|
||
| Plain files in Git are boring. Boring is good. | ||
|
|
||
| ### 2. Editors become culture | ||
|
|
||
| If your team writes in Markdown/MDX in Git, your culture becomes: | ||
|
|
||
| - “open a PR” | ||
| - “leave a comment” | ||
| - “fix it in the repo” | ||
|
|
||
| If your team writes in a SaaS editor, your culture becomes: | ||
|
|
||
| - “who has access?” | ||
| - “which space is that in?” | ||
| - “did the integration break again?” | ||
|
|
||
| Neither is inherently “right,” but they lead to different organizations. | ||
|
|
||
| ### 3. Your writers will change over time | ||
|
|
||
| Today your blog might be “founder + engineers.” | ||
| In two years, it might be “devrel + marketing + product + support.” | ||
|
|
||
| Choosing a stack that can evolve from **IDE-only → Git-based CMS → headless CMS** with minimal rewriting is underrated. | ||
|
|
||
| Git + MDX is a good foundation for that. | ||
|
|
||
| --- | ||
|
|
||
| ## So… What Would I Use If I Were Starting Today? | ||
|
|
||
| If I were a technical founder starting a new product today: | ||
|
|
||
| - For **blog + marketing + simple docs** | ||
| → I’d start with **Next.js or TanStack Start + MDX + GitHub**, no CMS. | ||
| - When non-engineers need to edit regularly | ||
| → I’d add a **Git-based CMS** like Keystatic on top. [oai_citation:14‡Keystatic](https://keystatic.com/?utm_source=chatgpt.com) | ||
| - If I ever hit real omnichannel, multi-locale complexity | ||
| → I’d consider **Sanity or Payload** and accept the trade-offs. [oai_citation:15‡Next.js Templates](https://nextjstemplates.com/blog/headless-cms-nextjs?utm_source=chatgpt.com) | ||
| - For standalone internal knowledge bases | ||
| → I’d probably just use **GitBook** and not overthink it. [oai_citation:16‡GitBook](https://gitbook.com/docs?utm_source=chatgpt.com) | ||
|
|
||
| That’s basically our philosophy behind Hyprnote’s own stack: | ||
| start with the simplest thing that respects **developer workflows, portability, and long-term ownership.** | ||
|
|
||
| The tools will change. | ||
| Your content shouldn’t have to. | ||
|
|
||
| --- | ||
|
|
||
| **This is Part 3 of our series on building a modern publishing workflow.** | ||
|
|
||
| - Part 1 – *Why We Write Our Blog in an IDE (Not a WYSIWYG Editor)* | ||
| - Part 2 – *Why Our CMS Is GitHub* | ||
| - Part 3 – *Choosing a CMS in 2025: A Guide for Technical Teams* | ||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Fix malformed coverImage and image URLs.
Lines 7 and 52 contain URLs that concatenate improperly, resulting in invalid paths. The string
public_imagesmerges directly with thehttps://protocol without proper separation.Line 7 (coverImage):
Current:
public_imageshttps://ijoptyyjrfqwaqhyxkxj.supabase.co/storage/v1/object/public/public_images/...Expected:
public_images/blog/bot-free-ai-meeting-assistants/cover.pngLine 52 (img src):
Same issue — URL segment duplicated without separator.
Apply this diff to fix line 7:
Apply this diff to fix line 52:
Also applies to: 52-52
🤖 Prompt for AI Agents