This example builds a Stackbit site starting from the Next.js starter. It renders simple pages with just a few simple fields from local markdown files.

Below you will find a link to the code, an option to generate your own Stackbit site from the code, and the following concepts:

The Code

This code is available on GitHub in the stackbit/example-nextjs-simple repo.

Warning: The code that powers this example uses new features. It is meant as a demonstration to teach basic concepts and is not ready to be used in production.

You can also clone this project into your own Stackbit site by clicking the button below:

Create with Stackbit

Rendering Basic Pages

The project is set up to render basic pages from content. It comes together with three pieces:

Content Source

These pages are placed in the content/pages directory. Pages can have a title, subtitle, and image in its frontmatter, along with content in the main body area. For example, here's the home page:

title: Home
subtitle: This is the home page.
image: /images/sentidos-humanos-kEq5QH9rUTM-unsplash.jpg

Laborum sit officia magna duis adipisicing ...

Page Template

The page template is placed at pages/[[...slug]].jsx.

Notice that we have removed the index.jsx file from the pages directory. That's because we're rendering pages with an optional catch all route. This is what enables us to nest pages without having templates explicitly nested in the pages directory. But that means we can't have any conflicting routes, which index.jsx would create.

This template has a getStaticPaths() method, which tells Next which pages to load. This function makes use of a getPagePaths() utility method, covered below.

export async function getStaticPaths() {
  const pagePaths = await getPagePaths();
  return { paths: pagePaths, fallback: false };

Next then runs a getStaticProps() function for each page. This is where we use a getPageProps() utility method to parse the markdown file for the requested route.

export async function getStaticProps({ params }) {
  const page = await getPageProps(params.slug);
  return { props: { page } };

Utility Methods

The utility methods are what makes everything work together. Take a look at the utils/pages.js file. This has a number of methods that read from the content/pages directory, parses the content, and makes it available to the template.

Each function is commented so you can see what it is responsible for.

Making Pages Editable in Stackbit

After you have a site that is rendering basic pages, the next step is to make the pages editable in Stackbit Studio.

We can make this happen by adding a stackbit.yaml file in the root of the project. The configuration file in the example project contains comments to better explain each item. Let's talk about a few of them.

Enabling Asset Uploads

Because pages have an image, we want to enable an asset uploading feature in Stackbit. And we want to store those images within the code repository. To do this, we add the assets setting:

  referenceType: static
  staticDir: public
  uploadDir: images
  publicPath: /

This tells Stackbit to store uploaded images to the public/images directory, and to reference the public directory as the root of the project, which is how Next.js will treat that directory.

The Page Model

models is where we define our Stackbit data models. You can read more about that setting in the reference guide.

Our config for pages says we have four fields: title, subtitle, and image.

    type: page
    label: page
      - name: title
        type: string
        label: Title
        required: true
      - name: subtitle
        type: string
        label: Subtitle
      - name: image
        type: image
        label: Image

We tell Stackbit that our pages can be found in the content/pages directory.

pagesDir: content/pages

Try it Yourself

That's it! That's how Stackbit works at its most basic. Give it a spin for yourself by clicking the button below to create your own Stackbit project from this example. Or create your own site using own of Stackbit's prebuilt themes.

Create with Stackbit