Keystatic & Astro

Keystatic is an open source, headless content-management system that allows you to structure your content and sync it with GitHub.

• An existing Astro project with server-side rendering (SSR) and output: 'hybrid' configured.

Add both the Markdoc (for content entries) and the React (for the Keystatic Admin UI Dashboard) integrations to your Astro project, using the astro add command for your package manager.

npx astro add react markdoc

pnpm astro add react markdoc

yarn astro add react markdoc

You will also need two Keystatic packages:

npm install @keystatic/core @keystatic/astro

pnpm install @keystatic/core @keystatic/astro

yarn add @keystatic/core @keystatic/astro

A Keystatic config file is required to define your content schema. This file will also allow you to connect a project to a specific GitHub repository (if you decide to do so).

Create a file called keystatic.config.ts in the root of the project and add the following code to define both your storage type (local) and a single content collection (posts):

import { config, fields, collection } from '@keystatic/core';

export default config({
  storage: {
    kind: 'local',
  },

  collections: {
    posts: collection({
      label: 'Posts',
      slugField: 'title',
      path: 'src/content/posts/*',
      format: { contentField: 'content' },
      schema: {
        title: fields.slug({ name: { label: 'Title' } }),
        content: fields.document({
          label: 'Content',
          formatting: true,
          dividers: true,
          links: true,
          images: true,
        }),
      },
    }),
  },
});

Keystatic is now configured to manage your content based on your schema.

The Keystatic Admin UI is a React app that runs in your Astro project.

The following steps will create a dashboard that lives in src/pages/keystatic/ for managing your site content.

1. Create a keystatic.page.ts in the project root, alongside your Keystatic config file.

   import { makePage } from '@keystatic/astro/ui'
   import keystaticConfig from './keystatic.config'
   
   export const Keystatic = makePage(keystaticConfig)

2. Create a new page called src/pages/keystatic/[...params].astro and mount the component on the client side only:

   ---
   import { Keystatic } from '../../../keystatic.page'
   export const prerender = false
   ---
   
   <Keystatic client:only />

3. Create a new file called src/pages/api/keystatic/[...params].ts that will create API routes for Keystatic’s Admin UI.

   import { makeHandler } from '@keystatic/astro/api'
   import keystaticConfig from '../../../../keystatic.config'
   
   export const all = makeHandler({
     config: keystaticConfig,
   })
   
   export const prerender = false

4. To launch your Keystatic Admin UI dashboard, start Astro’s dev server:

   npm run dev

5. Visit http://127.0.0.1:3000/keystatic in the browser to see the Keystatic Admin UI running.

1. In the Keystatic Admin UI dashboard, click on the “Posts” collection.

2. Use the button to create a new post. Add the title “My First Post” and some content, then save the post.

3. This post should now be visible from your “Posts” collection. You can view and edit your individual posts from this dashboard page.

4. Return to view your Astro project files. You will now find a new .mdoc file inside the src/content/posts directory for this new post:

   • Directorysrc/

     • Directorycontent/

       • Directoryposts/

         • my-first-post.mdoc

5. Navigate to that file in your code editor and verify that you can see the Markdown content you entered. For example:

   ---
   title: My First Post
   ---
   
   This is my very first post. I am **super** excited!

Use Astro’s Content Collections API to query and display your posts and collections, just as you would in any Astro project.

The following example displays a list of each post title, with a link to an individual post page.

---
import { getCollection } from 'astro:content'

const posts = await getCollection('posts')
---
<ul>
  {posts.map(post => (
    <li>
      <a href={`/posts/${post.slug}`}>{post.data.title}</a>
    </li>
  ))}
</ul>

To display content from an individual post, you can import and use the <Content /> component to render your content to HTML:

---
import { getEntry } from 'astro:content'

const post = await getEntry('posts', 'my-first-post')
const { Content } = await post.render()
---

<main>
  <h1>{post.data.title}</h1>
  <Content />
</main>

For more information on querying, filtering, displaying your collections content and more, see the full content collections documentation.

To deploy your website, visit our deployment guides and follow the instructions for your preferred hosting provider.

You’ll also probably want to connect Keystatic to GitHub so you can manage content on the deployed instance of the project.

• Check out the official Keystatic guide
• Keystatic starter template

More CMS guides