docs: add "creating a static blog with gatsby" blog post #1560
Conversation
|
Deploy preview ready! Built with commit 660a65f |
|
Deploy preview ready! Built with commit 660a65f |
|
Deploy preview failed. Built with commit 660a65f https://app.netlify.com/sites/gatsbygram/deploys/596fa3258ebdd929f450f38d |
|
It's alive! https://596f90dd7960b14d9c4b4421--gatsbyjs.netlify.com/blog/2017-07-19-creating-a-blog-with-gatsby/ Well the preview anyways :-) Looking really good! Adding some comments inline. |
|
|
||
| [gatsby-plugins]: https://www.gatsbyjs.org/docs/plugins/ | ||
|
|
||
| [gatsby-plugin-catch-links]: https://www.gatsbyjs.org/docs/packages/gatsby-plugin-catch-links/ |
There was a problem hiding this comment.
I changed all package links yesterday to /packages/* :-( #1549
| - A working repo demonstrating all of the aforementioned functionality of Gatsby | ||
| - [`@dschau/create-gatsby-blog-post`][create-gatsby-blog-post] | ||
| - A utility and CLI I created to scaffold out a blog post following the predefined Gatsby structure with frontmatter, date, path, etc. | ||
| - [Source code for this blog][blog-source-code] |
|
|
||
| *This blog post was originally published at https://objectpartners.com/2017/07/19/creating-a-static-blog-with-gatsby/* | ||
|
|
||
| Gatsby is an incredible static site generator that allows for React to be used as the underlying rendering engine to scaffold out a static site that truly has all the benefits expected in a modern web application. It does this by rendering dynamic React components into static HTML content via [server side rendering][react-dom-server] at build time. This means that your users get all the benefits of a static site such as the ability to work without JavaScript, search engine friendliness, speedy load times, etc. without losing the dynamism and interactivity that is expected of the modern web. Once rendered to static HTML, client-site React/JavaScript _can_ take over (if creating stateful components or logic in `componentDidMount`) and add dynamism to the staticly generated content. |
|
|
||
| Gatsby is an incredible static site generator that allows for React to be used as the underlying rendering engine to scaffold out a static site that truly has all the benefits expected in a modern web application. It does this by rendering dynamic React components into static HTML content via [server side rendering][react-dom-server] at build time. This means that your users get all the benefits of a static site such as the ability to work without JavaScript, search engine friendliness, speedy load times, etc. without losing the dynamism and interactivity that is expected of the modern web. Once rendered to static HTML, client-site React/JavaScript _can_ take over (if creating stateful components or logic in `componentDidMount`) and add dynamism to the staticly generated content. | ||
|
|
||
| Gatsby [recently released][gatsby-release] a v1.0.0 with a bunch of new features, including (but not limited to) the ability to create content queries with GraphQL, integration with various CMSs--including WordPress, Contentful, Drupal, etc., and route based code splitting to keep the end-user experience as snappy as possible. In this post, we'll take a deep dive into Gatsby and some of these new features by creating a static blog. Let's get to it! |
There was a problem hiding this comment.
Make all links pointing to gatsbyjs.org relative
There was a problem hiding this comment.
"Let's get to it" is a bit awkward. Perhaps "Let's get on it!"?
|
|
||
| ### Functional plugins | ||
|
|
||
| Functional plugins either implement some functionality (e.g. offline support, generating a sitemap, etc.) _or_ they extend Gatsby functionality and allow for content to be authored in typescript, sass, etc. |
There was a problem hiding this comment.
Perhaps change "they extend Gatsby functionality and allow for content to be authored in typescript, sass, etc."
to
"they extend Gatsby's webpack configuration adding support for typescript, sass, etc."
| } | ||
| ``` | ||
|
|
||
| We're using GraphQL to get all Markdown nodes and making them available under the `allMarkdownRemark` GraphQL property. Each exposed property (on `node`) is made available for querying against. We're effectively seeding a GraphQL "database" that we can then query against via page-level GraphQL queries. One note here is that the `exports.createPages` API expects a Promise to be returned, so it works seamlessly with the `graphql` function, which returns a Promise (althougn note a callback API is also available if that's more your thing). |
| * This sort isn't strictly necessary, but can be handy to know previous/next post | ||
| * so the sorted order can sometimes be helpful! | ||
| */ | ||
| const posts = result.data.allMarkdownRemark.edges |
There was a problem hiding this comment.
Sorting should be done in the query e.g. allMarkdownRemark(sort: { fields: [frontmatter_date], order: DESC})
|
|
||
| I won't go into quite as much detail for this section, because we've already done something very similar for our blog template! Look at us, we're pro Gatsby-ers at this point! | ||
|
|
||
| Gatsby has a standard for "listing pages," and they're placed in the root of our filesystem we specified in `gatsby-source-filesystem`, e.g. `src/pages/index.js`. So create that file if it does not exist, and let's get it working! Additionally note that any JavaScript files (typically React components!) will get a corresponding static HTML file when built. For instance, if we create `src/pages/tags.js`, the path `http://localhost:8000/tags.html` will be available within the browser and the statically generated site. |
There was a problem hiding this comment.
note that any JavaScript files (typically React components!)
These files have to export a valid React component or else Gatsby will yell at you :-)
There was a problem hiding this comment.
tags.js will become /tags/index.html when when statically built but its browser path is just /tags/ which is probably the least confusing way of describing it.
| return ( | ||
| <div className="blog-posts"> | ||
| {posts | ||
| .sort((a, b) => { |
There was a problem hiding this comment.
Do the sorting and filtering in the query
|
|
||
| OK! So we've followed a similar approach to our blog post template, so this should hopefully seem pretty familiar. Once more we're exporting `pageQuery` which contains a GraphQL query. Note that we're pulling a slightly different data set, specifically we are pulling an `excerpt` of 250 characters rather than the full HTML, as well as we are formatting the pulled date with a format string! GraphQL is awesome. | ||
|
|
||
| The actual React component is fairly trivial, but one important note should be made. It's important that when linking to internal content, i.e. other blog links, that it's always advisable to use `gatsby-link`. This is for a variety of reasons, but one key one is that the `Link` component includes the ability to use a `pathPrefix.` This is useful if this blog will be hosted on something like Github Pages, or an otherwise non-root domain level, which are both very common patterns. |
There was a problem hiding this comment.
"it's always advisable"
Make this stronger e.g. "you're required to use gatsby-link". Gatsby doesn't work if you don't use gatsby-link.
|
I believe I addressed all of your feedback @KyleAMathews. Let me know if it looks good now! |
|
Sweet, merging/publishing! |
|
Awesome, I'm super excited. Thank you so much for your feedback and help! |
Added the blog post per discussion with @KyleAMathews
Hope this looks good, let me know if I can help with anything!