Markdown and Content Integrations
Purpose and Scope
Astro treats written content as a first-class way to build websites, especially blogs, documentation, marketing pages, and other text-heavy experiences. The baseline authoring format is Markdown: local Markdown files can live under src/, Markdown under src/pages/ becomes routable pages, and frontmatter supplies structured metadata such as titles, descriptions, tags, or other project-specific fields. When a project grows from a few files into a content system, Astro encourages content collections so related entries share schemas, validation, type safety, editor support, and optimized query-and-render APIs.
The content integration family extends that built-in Markdown foundation. @astrojs/mdx adds MDX support for authors who need JSX-like component usage inside content, while @astrojs/markdoc adds Markdoc support for teams that prefer a structured documentation-oriented markup system. These integrations are different from UI renderers and deployment adapters: they participate in content compilation and Markdown-adjacent processing rather than enabling a framework island or selecting a server runtime. Sources: packages/integrations/markdoc/tsconfig.build.json, packages/integrations/mdx/tsconfig.build.json
Official Astro docs group integrations into front-end frameworks, adapters, and other integrations. The selected source paths mirror that taxonomy: Alpine is represented as a front-end integration, Cloudflare, Netlify, and Node are represented as adapters, and MDX and Markdoc are represented as content-focused integrations. Reading these packages together helps maintainers understand that all official integrations share the same monorepo build conventions, but each category connects to different Astro subsystems. Sources: packages/integrations/alpinejs/tsconfig.build.json, packages/integrations/cloudflare/tsconfig.build.json, packages/integrations/netlify/tsconfig.build.json, packages/integrations/node/tsconfig.build.json, packages/integrations/markdoc/tsconfig.build.json, packages/integrations/mdx/tsconfig.build.json
Relevant Source Files
packages/integrations/markdoc/tsconfig.build.json- Defines the Markdoc integration build project and shows its references into Astro core, internal helpers, the shared remark package, and Astro Prism syntax highlighting support.packages/integrations/mdx/tsconfig.build.json- Defines the MDX integration build project and shows its references into Astro core, internal helpers, shared remark support, and themarkdown/satteripackage.packages/integrations/alpinejs/tsconfig.build.json- Provides a contrasting front-end framework integration build shape, with a direct reference to Astro core.packages/integrations/cloudflare/tsconfig.build.json- Provides an adapter comparison point, includingsrcandvirtual.d.tsin the build and referencing helper and redirect packages.packages/integrations/netlify/tsconfig.build.json- Provides another adapter comparison point with the same source and virtual type inclusion pattern as Cloudflare.packages/integrations/node/tsconfig.build.json- Provides a server adapter comparison point withsrcandvirtual.d.tsincluded and references to Astro core and internal helpers.
Integration Family Model
A useful way to reason about Astro integrations is to ask what part of the project they extend. UI integrations such as Alpine unlock client-side framework behavior in component islands. Adapter integrations such as Cloudflare, Netlify, and Node select output behavior for server-side rendering or hosting targets. Markdown and content integrations instead extend the authoring and compilation path for content files. They are closer to content collections, Markdown rendering, frontmatter handling, syntax highlighting, and editor-aware schemas than to deployment wiring or browser hydration.
That distinction matters when choosing tools. If a project only needs GitHub Flavored Markdown with frontmatter, Astro already includes the authoring path. If authors need to embed interactive or reusable components directly within prose, MDX is the usual content integration. If a documentation system benefits from a constrained, structured markup vocabulary, Markdoc can be a better fit. Both integrations should still be understood as part of Astro’s content story: authored files become inputs to pages, layouts, collections, rendering helpers, and the generated site output.
The build references support this model. Both Markdoc and MDX reference ../../astro/tsconfig.json, which places them against the core package API surface. Both also reference ../../internal-helpers/tsconfig.json, indicating that official integrations can share internal monorepo utilities rather than duplicating package infrastructure. Most importantly for this page, both reference ../../markdown/remark/tsconfig.json, connecting them to the shared Markdown processing area rather than to adapter-only packages. Sources: packages/integrations/markdoc/tsconfig.build.json, packages/integrations/mdx/tsconfig.build.json
System-to-Code Mapping
The clearest source-level difference between the two content integrations is their adjacent Markdown dependency. Markdoc references ../../astro-prism/tsconfig.json, which aligns it with syntax highlighting concerns commonly needed in documentation-style content. MDX references ../../markdown/satteri/tsconfig.json, showing that its implementation has a different Markdown-related support dependency. The page should not treat MDX and Markdoc as identical parsers with different file extensions; they occupy the same integration category, but their build graph points to different supporting packages. Sources: packages/integrations/markdoc/tsconfig.build.json, packages/integrations/mdx/tsconfig.build.json
The comparison integrations reinforce the category boundary. The Alpine integration build config extends the shared build configuration and references Astro core, but it does not include the Markdown package references shown by MDX and Markdoc. Cloudflare, Netlify, and Node include ./src and ./virtual.d.ts, reflecting adapter packages that expose runtime-specific source and virtual types. Cloudflare and Netlify also reference ../../underscore-redirects/tsconfig.json, while Node does not. These differences are deployment-focused, not content-authoring focused. Sources: packages/integrations/alpinejs/tsconfig.build.json, packages/integrations/cloudflare/tsconfig.build.json, packages/integrations/netlify/tsconfig.build.json, packages/integrations/node/tsconfig.build.json
| Package area | Source path | Build references that matter here | What that tells readers |
|---|---|---|---|
| Markdoc content integration | packages/integrations/markdoc/tsconfig.build.json | astro, internal-helpers, markdown/remark, astro-prism | Markdoc is built as an Astro integration with shared Markdown processing and syntax highlighting support. |
| MDX content integration | packages/integrations/mdx/tsconfig.build.json | astro, internal-helpers, markdown/remark, markdown/satteri | MDX is built as an Astro integration with shared Markdown processing and an MDX-specific supporting Markdown package. |
| Alpine UI integration | packages/integrations/alpinejs/tsconfig.build.json | astro | UI framework integrations can have a much smaller direct build graph. |
| Cloudflare adapter | packages/integrations/cloudflare/tsconfig.build.json | astro, internal-helpers, underscore-redirects, virtual.d.ts | Adapter packages include runtime source and virtual types for deployment behavior. |
| Netlify adapter | packages/integrations/netlify/tsconfig.build.json | astro, internal-helpers, underscore-redirects, virtual.d.ts | Netlify follows the adapter pattern and shares redirect infrastructure. |
| Node adapter | packages/integrations/node/tsconfig.build.json | astro, internal-helpers, virtual.d.ts | Node follows the adapter pattern without the selected redirect package reference. |
Authoring Workflow
Start with the content format rather than the package name. For ordinary pages and posts, Markdown files can be imported directly, globbed with Vite, or organized into content collections. Content collections are the recommended path for groups of related entries because schemas make content predictable and give developers validation and editor assistance. Astro’s experimental content Intellisense can generate JSON schemas in .astro for collection entries, and the official docs call out support for .md, .mdx, and .mdoc content files when that feature is enabled.
Add MDX when authors need a prose-first file that can also invoke components. In an Astro project, that commonly means documentation pages with callouts, marketing pages with reusable design blocks, or blog posts that embed demos. Add Markdoc when the content system needs a more controlled vocabulary for documentation-like authoring. In both cases, the integration should be configured as an Astro integration, then the content files should be routed or queried through the same project-level content architecture used by Markdown.
A practical project sequence is: create or identify the content collection, decide which entries remain plain Markdown, introduce MDX or Markdoc only where the authoring model requires it, and keep layout decisions in Astro components. This keeps prose, schema, and page chrome separated. It also helps teams avoid treating an integration as a substitute for information architecture. The integration changes how content is parsed and compiled; collections, routes, layouts, and rendering helpers still determine how that content becomes a site.
Build and Maintenance Signals
All six selected integration build configs extend the shared monorepo TypeScript build configuration at ../../../configs/tsconfig.build.json. That common base is a maintenance signal: official integrations are not isolated examples, but packages built under the same TypeScript project-reference system as the rest of the repository. For contributors, this means changes to a content integration should be evaluated both as package behavior and as part of the workspace build graph. Sources: packages/integrations/alpinejs/tsconfig.build.json, packages/integrations/cloudflare/tsconfig.build.json, packages/integrations/markdoc/tsconfig.build.json, packages/integrations/mdx/tsconfig.build.json, packages/integrations/netlify/tsconfig.build.json, packages/integrations/node/tsconfig.build.json
The content integrations share enough structure to be reviewed together, but their dependency differences are important review cues. A change that touches common Markdown behavior may affect both MDX and Markdoc through markdown/remark. A change that touches syntax highlighting may be more relevant to Markdoc because of the astro-prism reference in the selected build config. A change in MDX-specific processing should be checked against the markdown/satteri reference. Those review paths are more precise than treating every official integration as interchangeable.
Next Steps
If you are choosing a content path for an Astro project, first read the Markdown and content collections guidance, then decide whether MDX or Markdoc solves a real authoring need. If you are contributing to the repository, inspect the integration package you are changing and follow the project-reference relationships shown here before widening the change. For adjacent topics, continue to markdown-mdx-content for authoring behavior, content-collections for structured content APIs, integrations-overview for integration mechanics, and configuration-reference for how integrations are registered in an Astro project.