Examples and Starters

Purpose and Scope

Astro examples and starters are practical entry points for learning the framework by reading or running a small project instead of starting from an empty directory. A starter is usually the first project shape a reader copies: it establishes the familiar Astro layout with src/, public/, package.json, astro.config.mjs, and tsconfig.json. An example is more focused: it demonstrates one capability such as content rendering, framework islands, server rendering, styling, or shared state. The official docs point readers toward starter projects for quick experimentation and describe the common project layout these examples rely on.

This page surveys how to use examples as learning material and how to recognize the source-backed pieces that turn an example into an Astro capability. The supplied repository evidence is centered on @astrojs/markdoc, so Markdoc is used here as a concrete example of a content-oriented starter feature: it adds a new content format, exports configuration helpers, exposes renderer components, and plugs into Astro through integration hooks. That pattern is useful when comparing blog, portfolio, MDX, Markdoc, Tailwind, SSR, and state-sharing examples: each example combines ordinary project files with one or more package-level capabilities.

Sources: packages/integrations/markdoc/package.json, packages/integrations/markdoc/src/index.ts

Relevant Source Files

• packages/integrations/markdoc/tsconfig.build.json — Shows the build-time relationships for the Markdoc integration, including references to Astro, internal helpers, remark markdown tooling, and Astro Prism.
• packages/integrations/markdoc/src/config.ts — Defines the public Markdoc configuration helper, component mapping helper, exported Markdoc object, custom heading node support, and configuration types.
• packages/integrations/markdoc/src/options.ts — Defines the integration options that examples can set when enabling Markdoc content.
• packages/integrations/markdoc/components/index.ts — Exports the Renderer component surface used by Markdoc rendering.
• packages/integrations/markdoc/src/index.ts — Implements the Astro integration entry point and hook behavior for registering Markdoc as a content entry type.
• packages/integrations/markdoc/package.json — Declares package metadata, public exports, scripts, dependencies, peer dependency on Astro, Node engine, and package files for @astrojs/markdoc.

Starter Families and Reader Tasks

A productive way to read Astro examples is to group them by the task they teach. Blog and documentation starters emphasize files as content, layouts, collections, and generated routes. Portfolio and landing-page starters emphasize components, styling, images, and static output. Hacker News or data-fetching examples emphasize loading external data before rendering pages. SSR examples introduce an adapter-driven deployment model and server-only behavior. Toolbar or developer-experience examples show how integrations can extend an Astro project. Tailwind examples focus on styling setup. MDX and Markdoc examples focus on rich authored content. State-sharing examples teach how multiple islands coordinate client-side state.

The official project-structure guidance is the common baseline across these families. A reader should expect project source under src/, unprocessed static assets under public/, and a manifest plus recommended Astro and TypeScript configuration files at the project root. That structure matters because examples are easier to compare when the folder layout stays stable. A Markdoc starter, for instance, is not a completely different kind of Astro application; it is an Astro project with an integration that teaches Astro how to load and render .mdoc content while still fitting into the standard project organization.

For interactive examples, the official state-sharing recipes are a useful companion to starters that include framework islands. Astro’s partial hydration model lets React, Vue, Svelte, Solid, Preact, Alpine, or vanilla scripts hydrate independently, so ordinary framework context may not span the whole page. The docs recommend Nano Stores for shared client-side storage because stores are lightweight and framework-agnostic. When evaluating an ecommerce, cart, dashboard, or multi-framework example, look for whether state is local to one island, shared through a store, or sent through browser events.

Markdoc as a Content Example

The Markdoc package demonstrates the anatomy of a content-focused example package. Its package metadata describes @astrojs/markdoc as adding Markdoc support to an Astro site, declares the package as an Astro integration, and publishes exports for the main integration, configuration helpers, renderer components, runtime modules, Prism, and Shiki extensions. Those exports explain what an example project can import directly: the default integration from the package root, config helpers from @astrojs/markdoc/config, and rendering support from @astrojs/markdoc/components. Sources: packages/integrations/markdoc/package.json, packages/integrations/markdoc/components/index.ts

At configuration time, the integration function returns an Astro integration named @astrojs/markdoc. Its astro:config:setup hook loads Markdoc configuration, registers a content entry type, and updates Vite SSR configuration so @astrojs/markdoc/prism and @astrojs/markdoc/shiki remain external. Its astro:server:setup hook watches supported Markdoc configuration files and restarts the dev server when those files change. In an example project, this is the difference between copying content files and actually teaching Astro’s content pipeline how to understand them. Sources: packages/integrations/markdoc/src/index.ts

The configuration helper layer is also important for example authors. defineMarkdocConfig() returns the supplied Astro Markdoc configuration, giving examples a clear place to define tags, nodes, context, and extended configurations. The exported component() helper distinguishes package component references from local component paths by checking whether the name is relative or absolute. That lets a Markdoc example map author-facing tags to Astro components without forcing every mapping to look the same. The package also exports Markdoc and a nodes object that includes a custom heading node. Sources: packages/integrations/markdoc/src/config.ts

Compact Reference

Area	Concrete surface	How examples use it
Integration package	@astrojs/markdoc	Add the default integration to an Astro project to enable Markdoc content.
Options	allowHTML, ignoreIndentation, typographer	Tune Markdoc parsing behavior for a starter or documentation site.
Config helper	defineMarkdocConfig(config)	Author a typed Markdoc configuration file for tags, nodes, context, and extensions.
Component helper	component(pathnameOrPkgName, namedExport?)	Map Markdoc tags to local components or package exports.
Components export	Renderer from @astrojs/markdoc/components	Render Markdoc output through the integration’s component surface.
Syntax highlighting exports	@astrojs/markdoc/prism, @astrojs/markdoc/shiki	Support examples that demonstrate code blocks and documentation-style content.
Runtime exports	@astrojs/markdoc/runtime, @astrojs/markdoc/runtime-assets-config	Support runtime behavior and asset configuration used by the package.

The options interface is intentionally small, which makes it a good fit for starter documentation. allowHTML controls whether authored Markdoc can contain HTML, ignoreIndentation affects parsing sensitivity, and typographer enables typographic transformations. A starter can expose these options in astro.config.mjs without overwhelming a new user. When comparing this with MDX, Tailwind, or adapter examples, look for the same pattern: a small public configuration surface sits on top of package internals, while the project still follows the same Astro application structure. Sources: packages/integrations/markdoc/src/options.ts, packages/integrations/markdoc/package.json

Build and Maintenance Signals

The Markdoc integration’s build configuration shows that content examples are not isolated from the rest of Astro. Its TypeScript build references the core Astro package, internal helpers, the markdown remark package, and Astro Prism. That dependency graph explains why a Markdoc example can feel native: it is built against the same core and markdown-related packages that support broader Astro content workflows. The package scripts also provide build, build:ci, dev, and test commands, which are the package-level equivalent of the workflows a contributor expects when validating an example or integration. Sources: packages/integrations/markdoc/tsconfig.build.json, packages/integrations/markdoc/package.json

The package metadata is also a maintenance signal for starter authors. The peer dependency requires Astro, the Node engine is declared as >=22.12.0, and the published files include components, dist, and template. Dependencies such as @markdoc/markdoc, github-slugger, htmlparser2, and workspace packages such as @astrojs/internal-helpers and @astrojs/prism indicate the kinds of behavior this integration owns: parsing Markdoc, generating heading slugs, handling HTML, and coordinating with Astro’s own helper and highlighting packages. Sources: packages/integrations/markdoc/package.json

How to Use This Page

When choosing a starter, begin with the reader task rather than the package name. Use a blog or documentation starter when content structure is the main problem, a portfolio or Tailwind starter when design iteration is the main problem, an SSR starter when deployment runtime behavior matters, and a state-sharing example when partially hydrated islands need to communicate. Then inspect the integration or package surfaces that the starter imports. For Markdoc, that means checking the integration entry point, config helper, options, renderer component, and syntax-highlighting exports before changing project-level content files.

A good next step is to pair this survey with the project structure and content pages. Project structure explains where example files belong; content collections and Markdown or MDX pages explain how authored content becomes routes; integrations pages explain how packages like @astrojs/markdoc extend the build. If you are reading examples to contribute back to the repository, also run the relevant package scripts and check whether a change affects only a starter, a published integration, or Astro’s shared content pipeline.