#Markdown/MDX vs. CMS

19 messages · Page 1 of 1 (latest)

flat loom
#

For personal website which will be operated by me. Which is better? List pros and cons.

lost plinthBOT
#

Hi @flat loom. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:

#

For a personal site you manage yourself, both approaches are valid in Astro. Here’s how they compare, based only on what the docs state.

Markdown / MDX in Astro

Astro has built-in support for Markdown with frontmatter; you can author content in GitHub Flavored Markdown and render it directly in .astro components or as pages (src/pages/*.md). [Markdown in Astro; Markdown/MDX pages]

You can optionally add the MDX integration to use variables, JSX expressions, and components inside your content, or to reuse existing .mdx files. [MDX in Astro; MDX in Astro usage]

Pros

#
  • No extra services: Everything lives in your repo under src/, no external dashboard or database needed. [Markdown in Astro]
  • Simple workflow: You just edit files in a code editor; great if you’re comfortable with Git and Markdown. [Migrating from GitBook]
  • Type-safe content collections: You can define schemas, get validation and TypeScript types for structured content like blog posts. [Markdown in Astro]
  • Good for relatively static content: Docs recommend build-time collections and Markdown for content like blog posts, docs, product descriptions. [Live collections: when to use]
  • MDX flexibility (optional): MDX lets you mix content and components, and is suggested as a powerful option for rich content. [MDX integration; <Markdown /> upgrade note]

Cons

#
  • You must be comfortable editing files: Unlike a dashboard, everything is done in a code editor and version control. [Migrating from WordPress]
  • No visual/WYSIWYG interface built-in: Just text files; any preview comes from running the dev server.
  • More manual structure: You define your own schemas (via content collections) instead of having a CMS enforce fields for you. [Markdown in Astro]

Using a CMS with Astro

Astro can fetch content from many headless CMSs (WordPress, Storyblok, Sanity, etc.), using either dedicated integrations or generic JavaScript SDKs. [Use a CMS; Which CMSes work well]

Pros

  • Visual editing & dashboards: CMSes provide rich text editors, asset management, and collaboration tools. [Why use a CMS?]
  • Structured content types: You can define models (e.g. “Post”, “Product”) and enforce required fields to avoid incomplete entries. [Why use a CMS?]
  • Good for frequently updated or complex content: Docs suggest CMS-style workflows for content that follows a particular structure and benefits from dashboard-like management. [Why use a CMS?]
  • Can reuse existing systems: For example, Astro can use WordPress as a headless CMS and fetch your existing content. [Migrating from WordPress]

Cons

#
  • Extra moving parts: You depend on an external service (hosting, auth, permissions, etc.) in addition to your Astro site. [Use a CMS]
  • More setup & integration: You must configure APIs/SDKs or integrations and write code to fetch and render content. [Use a CMS]
  • Overkill for simple personal sites: The docs explicitly note you can use Astro without a CMS because Markdown is built-in. [Use a CMS]

Which fits a personal site you operate alone?

From the docs:

  • Astro works perfectly without a CMS, using only Markdown/MDX. [Use a CMS]
  • Markdown/MDX and content collections are positioned as the default for content-driven, relatively static sites (blogs, docs, personal sites). [Why Astro; Live collections: when to use]

Based on that, for a personal site managed only by you, the docs strongly support:

  • Start with Markdown (and optionally MDX + content collections).
  • Consider a CMS later only if you specifically want a visual editor, shared editing with others, or a dashboard-style experience. [Why use a CMS?]

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

#

@flat loom Kapa.ai is still learning and improving, please let me know how I did by reacting below.

flat loom
#

@lost plinth Markdown vs MDX? if my content will have components for image grid/gallery, code syntax highlighter, content type of project case study which heavy on image and layout. Optimization etc.

#

@lost plinth Markdown vs MDX? if my content will have components for image grid/gallery, code syntax highlighter, content type of project case study which heavy on image and layout. Optimization etc.

lost plinthBOT
#

Let me check the knowledge base for you again. One moment! :books:

#

For richly designed, component-heavy case studies, the docs lean toward MDX over plain Markdown.

What Markdown gives you

Markdown in Astro:

Limitations:

  • No components: You cannot embed Astro/React/etc. components directly in .md. [Markdown in Astro]
  • No <Image /> / <Picture /> in .md — only ![alt](src) or <img> (public/remote only). [Images in Markdown]
  • Complex layouts (image grids, galleries, custom layout blocks) must be handled by the layout component around the Markdown, not inline in the content.

What MDX adds

The MDX integration:

#
  • Lets you write Markdown plus JSX expressions and components inside .mdx. [Why MDX; MDX in Astro]
  • Allows using Astro components and framework components directly in MDX, e.g. galleries, cards, callouts. [Using components in MDX]
  • Supports Astro’s <Image /> and <Picture /> components inside MDX by importing them, giving you full control over image optimization and attributes. [Images in MDX]
  • Still supports standard ![alt](src) syntax for optimized local images, same as Markdown. [Update Markdown, MDX, Markdoc]
  • Keeps frontmatter support, plus extra exported variables (e.g. export const title = '...'). [MDX in Astro]

This is ideal for:

  • Image grids/galleries: You can author a reusable Gallery.astro / ImageGrid.astro and drop it into content:

    import Gallery from '../components/Gallery.astro';

<Gallery images={[img1, img2, img3]} />

    [Using components in MDX]

#
  • Custom image optimization: Use <Image /> for fine‑grained control (sizes, formats) where needed, plus ![alt](src) for simpler cases. [Images in MDX]
  • Code syntax highlighting: Configure syntax highlighting globally (Markdown/MDX share config), then write fenced code blocks in MDX. [MDX configuration]
  • Rich case-study layouts: Mix headings/paragraphs with bespoke layout components (two‑column sections, timelines, metrics blocks, etc.) via JSX tags. [Using components in MDX]

Optimization aspects

  • Markdown .md:

    • Image optimization: via ![alt](src) for src/ images; no component-based <Image /> control. [Images in Markdown]
    • Layout optimization: handled mostly in surrounding layout components.

  • MDX .mdx:

    • Same ![alt](src) optimization for local images plus <Image /> / <Picture /> for more control. [Images in MDX]
    • Can encapsulate heavy layouts (galleries, complex sections) into reusable components, helping you keep content clean while still optimized.

Summary for your use case

For “project case study” pages that are:

  • heavy on images, custom layout, and reusable components (galleries, grids),
  • need image optimization and good control over how media is rendered,

the docs suggest that MDX is the better fit, because you can:

#
  • still use Markdown-style content and optimized ![alt](src) images,
  • and, crucially, embed Astro components and <Image /> directly in your content for complex UI and optimization control. [Why MDX; Images in MDX]

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

#

@flat loom Kapa.ai is still learning and improving, please let me know how I did by reacting below.

flat loom
#

@lost plinth how about using default html tag for wrapping markdown images, like example below:

<div class="column-3">
alt
alt
alt
</div>

lost plinthBOT
#

Let me check the knowledge base for you again. One moment! :books:

#

You can wrap Markdown images in HTML like that in Markdown and MDX, but there are some limits and differences:

1. Plain Markdown (.md)

Astro’s Markdown supports mixing HTML and Markdown, so this pattern is valid:

<div class="column-3">
![alt](../assets/img1.png)
![alt](../assets/img2.png)
![alt](../assets/img3.png)
</div>

Those ![alt](src) images:

Just note:

2. MDX (.mdx)

In MDX, the same pattern works and you also gain components:

<div class="column-3">
![alt](../assets/img1.png)
![alt](../assets/img2.png)
![alt](../assets/img3.png)
</div>

Plus you can instead import and use <Image /> / <Picture /> or your own gallery component if you want more control over layout/optimization inside that <div>. [Images in MDX files]

3. Markdoc (only if you use it)

#

Markdoc does not treat HTML as semantic content by default; you’d need allowHTML: true in the Markdoc integration to mix HTML and Markdoc. [allowHTML option]

So for your use case (simple columns):

  • Yes, wrapping ![alt](src) inside a <div class="column-3"> is supported and the images will still be processed as Markdown images, as long as you’re in .md or .mdx.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: