diff --git a/docs/docs/adding-markdown-pages.md b/docs/docs/adding-markdown-pages.md index 8bba5c184cda5..afab0a2dc4ff0 100644 --- a/docs/docs/adding-markdown-pages.md +++ b/docs/docs/adding-markdown-pages.md @@ -2,7 +2,179 @@ title: Adding Markdown Pages --- -This is a stub. Help our community expand it. +Gatsby can use markdown files to create pages in your site. +You add plugins to read and understand folders with markdown files and from them create pages automatically. -Please use the [Gatsby Style Guide](/docs/gatsby-style-guide/) to ensure your -pull request gets accepted. +Here's the steps Gatsby follows for making this happen. + +1. Read files into Gatsby from the filesystem +2. Transform markdown to HTML and frontmatter to data +3. Create a page component for the markdown files +4. Programmatically create pages using Gatsby's node.js `createPage` API + +### Read files into Gatsby from the filesystem - `gatsby-source-filesystem` + +Use the plugin [`gatsby-source-filesystem`](/packages/gatsby-source-filesystem/#gatsby-source-filesystem) to read files. + +#### Install + +`npm i --save gatsby-source-filesystem` + +Now open `gatsby-config.js` to add this plugin to the plugin array. + +To add a plugin, add either a string (the plugin name) or to pass options, an object. +For `gatsby-source-filesystem` we pass an object so we can set the file system path: + +```javascript +plugins: [ + { + resolve: `gatsby-source-filesystem`, + options: { + path: `${__dirname}/path/to/markdown/files`, + name: "markdown-pages", + }, + }, +]; +``` + +Now that we've "sourced" the markdown files from the filesystem, we can now "transform" the markdown to HTML and the YAML frontmatter to JSON. + +### Transforming markdown — `gatsby-transformer-remark` + +We'll use the plugin [`gatsby-transformer-remark`](/packages/gatsby-transformer-remark/) to recognise files which are markdown and read its content. It will convert the frontmatter metadata part of your markdown file as `frontmatter` and the content part as HTML. + +`npm i --save gatsby-transformer-remark` + +Add this to `gatsby-config.js` after the previously added `gatsby-source-filesystem`. + +```javascript +plugins: [ + { + resolve: `gatsby-source-filesystem`, + options: { + path: `${__dirname}/path/to/markdown/files`, + name: "markdown-pages", + }, + }, + `gatsby-transformer-remark`, +]; +``` + +#### Note on creating markdown files. + +When you create a Markdown file, at the top of the file, add the block below. You can have different key value pairs that are relevant to your website. This block will be parsed by `gatsby-transformer-remark` as `frontmatter`. The GraphQL API will provide this data in our React components. + +``` +--- +path: "/blog/my-first-post" +date: "2017-11-07" +title: My first blog post" +--- +``` + +### Create a page template for the markdown data. + +Create a folder in the `/src` directory of your Gatsby application called `templates`. +Now create a `blogTemplate.js` inside it with the following content. + +```jsx +import React from "react"; + +export default function Template({ + data, // this prop will be injected by the GraphQL query below. +}) { + const { markdownRemark } = data; // data.markdownRemark holds our post data + const { frontMatter, html } = markdownRemark; + return ( +