Gatsby + Gastby-MDX + Netlify-CMS Starter
Extended from the Gatsby starter, this starter aims to provide an example for using Gatsby-MDX with Netlify.
- Support React Components in your CMS editing workflow through MDX
- Read .MD and .MDX files as pages automatically
- Swap page template based on CMS key, allowing editors to choose different page templates
- Support CMS configurations that save markdown in frontmatter fields with an mdx-enabled markdown renderer component (with example)
- Hide pages from being editable by the CMS
- Extend Netlify CMS editor to support the insertion of a React component, allowing your editors to include things like buttons or testimonials
- Swap default HTML elements in posts for React components, allowing for greater control
- All the other Gatsby + MDX stuff
yarn develop or
npm run develop @ localhost:8000
Your development environment will read from your local .md files, but will not hot reload changes to the .md files. To make a change in the markdown and see it reflected:
- Stop the dev server
rm -rf .cacheto remove the gatsby cache
- Restart the dev server
Local Admin Panel
While running the dev server:
Log in using your Netlify credentials.
Use the local admin to verify changes to your CMS config. Please note that the state of all markdown content will reflect the state of the github master branch, NOT your local changes.
yarn build or
npm run build
Go through each of these directories to understand the project and extend from it.
src/cms - Utilities for working with FrontMatter which Netlify CMS depends on, example previews and example widget registration. This folder also includes a whitelist of components that will be included in the MDX render scope in cms-components.constants.js.
src/components - Components, mostly default with a few additions such as a call to action and a smart link.
src/core - Core components to render markdown, catch errors
src/page-templates - Templates for CMS pages and an entry template component that will be used to determine what template should be shown where. Look in particular at cms-entry.template.js
src/pages - Editor content. All CMS-created pages will live in the content directory. Other pages may be modified from the CMS, but cannot be created or deleted.
static/admin - CMS Editor configuration.
Templates and Template Keys
CMSTemplate component in conjunction with the hidden
templateKey var controls which template will be used to render each content page. The
CMSTemplate component will try to map the value of
templateKey to a component, and fall back to a default if nothing is found. Please see the component for more details.
Markdown and Frontmatter
Due to the way Netlify works, some CMS content is saved as Markdown
frontmatter rather than actual markdown. Therefore, fields with a markdown editor will save a raw markdown string. It is up to our templates to correctly parse markdown. For this, we have the core component
<RenderMarkdown> which will parse MDX upon receiving an MDX string and include supplied React components as appropriate. Under the hood, this uses @mdx/runtime so please look there fore configuration details.
Gatsby's default starter
Kick off your project with this default boilerplate. This starter ships with the main Gatsby configuration files you might need to get up and running blazing fast with the blazing fast app generator for React.
Have another more specific idea? You may want to check out our vibrant collection of official and community-created starters.
🚀 Quick start
Create a Gatsby site.
Use the Gatsby CLI to create a new site, specifying the default starter.
# create a new Gatsby site using the default starter npx gatsby new my-default-starter https://github.com/gatsbyjs/gatsby-starter-default
Navigate into your new site’s directory and start it up.
cd my-default-starter/ gatsby develop
Open the source code and start editing!
Your site is now running at
Note: You'll also see a second link:
http://localhost:8000/___graphql. This is a tool you can use to experiment with querying your data. Learn more about using this tool in the Gatsby tutorial.
my-default-starterdirectory in your code editor of choice and edit
src/pages/index.js. Save your changes and the browser will update in real time!
🧐 What's inside?
A quick look at the top-level files and directories you'll see in a Gatsby project.
. ├── node_modules ├── src ├── .gitignore ├── .prettierrc ├── gatsby-browser.js ├── gatsby-config.js ├── gatsby-node.js ├── gatsby-ssr.js ├── LICENSE ├── package-lock.json ├── package.json └── README.md
/node_modules: This directory contains all of the modules of code that your project depends on (npm packages) are automatically installed.
/src: This directory will contain all of the code related to what you will see on the front-end of your site (what you see in the browser) such as your site header or a page template.
srcis a convention for “source code”.
.gitignore: This file tells git which files it should not track / not maintain a version history for.
.prettierrc: This is a configuration file for Prettier. Prettier is a tool to help keep the formatting of your code consistent.
gatsby-browser.js: This file is where Gatsby expects to find any usage of the Gatsby browser APIs (if any). These allow customization/extension of default Gatsby settings affecting the browser.
gatsby-config.js: This is the main configuration file for a Gatsby site. This is where you can specify information about your site (metadata) like the site title and description, which Gatsby plugins you’d like to include, etc. (Check out the config docs for more detail).
gatsby-node.js: This file is where Gatsby expects to find any usage of the Gatsby Node APIs (if any). These allow customization/extension of default Gatsby settings affecting pieces of the site build process.
gatsby-ssr.js: This file is where Gatsby expects to find any usage of the Gatsby server-side rendering APIs (if any). These allow customization of default Gatsby settings affecting server-side rendering.
LICENSE: Gatsby is licensed under the MIT license.
package.jsonbelow, first). This is an automatically generated file based on the exact versions of your npm dependencies that were installed for your project. (You won’t change this file directly).
package.json: A manifest file for Node.js projects, which includes things like metadata (the project’s name, author, etc). This manifest is how npm knows which packages to install for your project.
README.md: A text file containing useful reference information about your project.
🎓 Learning Gatsby
Looking for more guidance? Full documentation for Gatsby lives on the website. Here are some places to start:
For most developers, we recommend starting with our in-depth tutorial for creating a site with Gatsby. It starts with zero assumptions about your level of ability and walks through every step of the process.
To dive straight into code samples, head to our documentation. In particular, check out the Guides, API Reference, and Advanced Tutorials sections in the sidebar.