gatsbyjs · AishaBlake · Apr 30, 2020 · Mar 3, 2020 · Mar 3, 2020 · Mar 3, 2020
diff --git a/.circleci/config.yml b/.circleci/config.yml
@@ -201,6 +201,7 @@ jobs:
             sed -i ':a;N;$!ba;s/,\n\s*"workspaces":\s\[[^]]*]//g' package.json
       - <<: *install_node_modules
       - run: yarn lint:code
+      - run: yarn lint:docs
       - run: yarn lint:other
 
   typecheck:

diff --git a/.remarkrc.js b/.remarkrc.js
@@ -0,0 +1,39 @@
+module.exports = {
+  plugins: [
+    ["remark-frontmatter", "yaml"],
+    "remark-preset-lint-recommended",
+    "remark-preset-lint-markdown-style-guide",
+
+    // additional remark-lint rules
+    ["remark-lint-list-item-indent", "space"],
+    "remark-lint-no-duplicate-headings-in-section",
+    "remark-lint-no-reference-like-url",
+    ["remark-lint-ordered-list-marker-value", "ordered"],
+
+    // We would like these rules to be enabled, but they require significant content changes
+    // and need additional PRs to be implemented
+    ["remark-lint-emphasis-marker", false],
+    ["remark-lint-heading-increment", false],
+    ["remark-lint-no-heading-punctuation", false],
+    ["remark-lint-list-item-spacing", false],
+
+    // The following rules are disabled because they are inconsistent to the
+    // Gatsby Style Guide.
+
+    // We use soft-wrapped paragraphs for ease of diffing/translation.
+    ["remark-lint-maximum-line-length", false],
+    // We don't restrict the length of headings.
+    ["remark-lint-maximum-heading-length", false],
+    // We use duplicate headings sometimes, e.g. multiple "Directions" in Recipes.
+    // Use no-duplicate-headings-in-section instead.
+    ["remark-lint-no-duplicate-headings", false],
+    // We use emphasis as notes or warnings in a couple places, which triggers this rule.
+    ["remark-lint-no-emphasis-as-heading", false],
+    // YouTube and Giphy embeds in the docs use literal URLs.
+    ["remark-lint-no-literal-urls", false],
+    // We use `[shortcuts]` for convenience.
+    ["remark-lint-no-shortcut-reference-link", false],
+    // We use brackets in a lot of places as argument lists and do not want to escape them.
+    ["remark-lint-no-undefined-references", false],
+  ],
+}
diff --git a/docs/blog/100days/comments/index.md b/docs/blog/100days/comments/index.md
@@ -20,7 +20,7 @@ There are multiple ways to accept user-generated content on your site. So, inste
 
 ### Gatsby Comments Resources
 
-#### Option 1. Embed comments using JavaScript.
+#### Option 1. Embed comments using JavaScript
 
 _Pros and cons_: This approach is the simplest option for adding comments to your site. You can choose many low cost or free comment services, like Disqus and Facebook Comments. However, this method will have a negative impact on your site performance, and has privacy implications for your users.
 

diff --git a/docs/blog/2017-10-16-making-website-building-fun/index.md b/docs/blog/2017-10-16-making-website-building-fun/index.md
@@ -225,12 +225,12 @@ before we get to actually coding the frontend.
 
 For example, how does a single image typically get on a website?
 
-1.  A page is designed
-2.  Specific images are chosen
-3.  The images are resized (with ideally multiple thumbnails to fit different
-    devices)
-4.  And finally, the image(s) are included in the HTML/CSS/JS (or React
-    component) for the page.
+1. A page is designed
+2. Specific images are chosen
+3. The images are resized (with ideally multiple thumbnails to fit different
+   devices)
+4. And finally, the image(s) are included in the HTML/CSS/JS (or React
+   component) for the page.
 
 What makes gatsby-image really interesting is it's _seamlessly integrated into
 Gatsby's data layer_ which has native image processing capabilities.
@@ -276,10 +276,10 @@ export const query = graphql`
 So instead of a long pipeline of tasks to setup optimized images for your site,
 the steps now are:
 
-1.  Install gatsby-image
-2.  Decide what size of image you need (125x125 in the example above)
-3.  Add your query and the gatsby-image component to your page
-4.  And… that's it!
+1. Install gatsby-image
+2. Decide what size of image you need (125x125 in the example above)
+3. Add your query and the gatsby-image component to your page
+4. And… that's it!
 
 Now playing with images is fun! Want to tweak your design? No problem, just
 change your query a bit and see how the page updates. By eliminating the

diff --git a/...og/2017-10-20-from-wordpress-to-developing-in-react-starting-to-see-it/index.md b/...og/2017-10-20-from-wordpress-to-developing-in-react-starting-to-see-it/index.md
@@ -133,7 +133,7 @@ focus on context without having to grok SCSS again, reducing mental friction.
 Following the [tutorial on Gatsbyjs](/tutorial/) I built
 up my project from scratch, breaking things profusely at first, but it honestly
 didn’t take long to gain confidence enough so that I launched my first site at
-[https://freebabylon5.com](https://freebabylon5.com)
+https://freebabylon5.com
 recently.
 
 Be warned: the tutorial isn’t quite finished yet, you might be better off
@@ -154,7 +154,7 @@ and others) for a faster, more efficient development experience.
 I'm glad to say I'm sold on the idea and methods of developing with JavaScript,
 and React in particular. The site I've re-built from WordPress into Gatsby.js is
 now live at
-[https://freebabylon5.com](https://freebabylon5.com).
+https://freebabylon5.com.
 
 Together with my colleagues at
 [Indigo Tree](https://indigotree.co.uk)

diff --git a/docs/blog/2017-11-09-why-i-created-my-blog-with-gatsby-and-contentful/index.md b/docs/blog/2017-11-09-why-i-created-my-blog-with-gatsby-and-contentful/index.md
@@ -328,7 +328,7 @@ projects.
 And so it was that my quest for having a very cheap, secure, fast, scalable,
 customizable and easy to maintain blog concluded. It's certainly not the most
 exciting or well-looking blog out there, but it's everything I wanted it to be
--- both as a developer and as a blogger.
+— both as a developer and as a blogger.
 
 Personally I cannot wait to see how far can the limits of technologies like
 Gatsby.js can be stretched, and with the advent and spread of new architectural

diff --git a/docs/blog/2017-12-06-gatsby-plus-contentful-plus-netlify/index.md b/docs/blog/2017-12-06-gatsby-plus-contentful-plus-netlify/index.md
@@ -40,11 +40,11 @@ The following is a report on my high-level experience of using Gatsby with
 Contentful, Netlify and Algolia and the problems they solve — without getting
 down into code.
 
-# Static to the Rescue?
+## Static to the Rescue?
 
 I know it’s bad to make assumptions, but I’m going to assume that if you’re here
 and reading this, you at least know a little about the perks of static sites and
-the JAMstack. If not, check out [https://jamstack.org/](https://jamstack.org/)
+the JAMstack. If not, check out https://jamstack.org/
 for a quick breakdown on why web development is, for lack of a better phrase,
 “going back to the basics.”
 
@@ -76,7 +76,7 @@ that’s a common consensus.
 
 Okay, now back to some static hurdles.
 
-# A Problem of Content
+## A Problem of Content
 
 Our site has a lot of content (~300 articles) that needs to be maintained by
 non-developers, my co-workers. This meant we needed an approachable interface
@@ -90,7 +90,7 @@ repo.
 > plugin that pulls in content via a WordPress API. However, to me, this was not
 > appealing because I was trying to avoid hosting a traditional CMS entirely.
 
-# Solution: Contentful + Gatsby
+## Solution: Contentful + Gatsby
 
 Contentful is a hosted [headless CMS](/docs/headless-cms/) with a fantastic user experience. It’s
 similar to having a backend like WordPress, but you are fully responsible for
@@ -159,7 +159,7 @@ get converted to HTML via a transformer plugin within Gatsby. The markdown
 editing in Contentful is quite practical with standard WYSIWYG-like editor
 features. I haven’t heard any complaints from my co-workers.
 
-# Searching for a Search Solution
+## Searching for a Search Solution
 
 Another “problem” with static sites is the lack of out-of-the-box site search.
 Most search implementations occur between the server and the database. As a doc
@@ -179,7 +179,7 @@ something that would operate client-side, but that had the search brains still
 residing in the cloud somewhere. Though an option, I didn’t have time to build
 my own solution.
 
-# Solution: Algolia + Gatsby
+## Solution: Algolia + Gatsby
 
 This solution was a bit of a trial and error process for me. I had seen many doc
 sites use Algolia online in my dev travels. I knew it offered a usable free tier
@@ -235,7 +235,7 @@ Reactjs.org repo had the answer right in their
 They use DocSearch instead of rolling their own indexing and search interface.
 Oh well.
 
-# Hosting & Deployment
+## Hosting & Deployment
 
 A great thing about static sites is that you can host them just about anywhere.
 You get a folder of pre-built files that you can throw up on any web server and
@@ -259,7 +259,7 @@ for free?
 Luckily I already knew the answers to these questions because I had already
 discovered Netlify for some other projects.
 
-# Solution: Netlify + Gatsby
+## Solution: Netlify + Gatsby
 
 Plugging any static site into the Netlify workflow is a no brainer, but after I
 found Gatsby, I knew there was no other option for me. These two pair so well
@@ -317,7 +317,7 @@ addition, and Netlify rebuilds the site and deploys it.
 
 It’s a match made in JAMstack heaven.
 
-# Is it Magic?
+## Is it Magic?
 
 Gatsby makes building the site fun and painless. It gets out of the way and lets
 you be creative with your craft — yet also adds some insane perks, like

diff --git a/docs/blog/2017-12-07-taking-gatsby-for-a-spin/index.md b/docs/blog/2017-12-07-taking-gatsby-for-a-spin/index.md
@@ -21,7 +21,7 @@ GatsbyJS is based on React which means that you'll be writing almost everything
 
 ### GraphQL
 
-Gatsby was my first introduction to [GraphQL](https://graphql.org/learn/) and I'm loving it already. GraphQL is a query language used by Gatsby to let you connect to all kinds of APIs. With it as an abstraction layer, you can pull in all the data you can think of and utilize it in your app. Gatsby comes with plugins to pull in data from several APIs, CMS systems and local files. With GraphQL, you're able to query data from all these sources in a clear and readable way. The data is instantly available in your components and that's just super cool. Also, it comes with a browser-based IDE called Graph*i*QL which starts along with your development environment. You can use it to see which queries are available, test them out, and see what data these queries return.
+Gatsby was my first introduction to [GraphQL](https://graphql.org/learn/) and I'm loving it already. GraphQL is a query language used by Gatsby to let you connect to all kinds of APIs. With it as an abstraction layer, you can pull in all the data you can think of and utilize it in your app. Gatsby comes with plugins to pull in data from several APIs, CMS systems and local files. With GraphQL, you're able to query data from all these sources in a clear and readable way. The data is instantly available in your components and that's just super cool. Also, it comes with a browser-based IDE called Graph_i_QL which starts along with your development environment. You can use it to see which queries are available, test them out, and see what data these queries return.
 
 ![Screenshot of GraphiQl](./grahiql_screenshot.png "GraphiQL")
 
@@ -49,7 +49,7 @@ Gatsby definitely delivers on speed. The whole PRPL pattern thing seems to work
 
 ### GraphQL is amazing
 
-Data from anywhere with static output. That's sort of the holy grail isn't it? Right now the data I use in this site comes from markdown files, but I can already see that switching to another content source is going to be a breeze with GraphQL. The queries are clean and readable and the Graph*i*QL IDE is the perfect helper. In a way, GraphQL allows you to separate your frontend from the type of data source.
+Data from anywhere with static output. That's sort of the holy grail isn't it? Right now the data I use in this site comes from markdown files, but I can already see that switching to another content source is going to be a breeze with GraphQL. The queries are clean and readable and the Graph_i_QL IDE is the perfect helper. In a way, GraphQL allows you to separate your frontend from the type of data source.
 
 ```javascript
 export const query = graphql`

diff --git a/docs/blog/2018-01-22-getting-started-gatsby-and-wordpress/index.md b/docs/blog/2018-01-22-getting-started-gatsby-and-wordpress/index.md
@@ -137,8 +137,8 @@ While this isn't a tutorial -- more a guided walkthrough of me familiarizing and
 
 ## Sidenotes
 
-1.  You [don't need to know GraphQL](https://github.com/gatsbyjs/gatsby/issues/1172#issuecomment-308634739) to get started with Gatsby. I didn't. It's been a good introduction.
-2.  Gatsby makes heavy use of [plugins](/docs/plugins/) — both official and community — for a lot of things, from one that implements [Google Analytics](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-plugin-google-analytics), to one that adds [GitHub's accessibility error scanner](https://github.com/alampros/gatsby-plugin-accessibilityjs) to all pages.
-3.  Read through some of the source code. I particularly enjoyed reading through [the bootstrap process](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby/src/bootstrap/index.js). (It's beautifully commented).
-4.  Gatsby.js is a static Progressive Web App (PWA) generator, but to be PWA friendly (at least according to the [Lighthouse PWA audit](https://developers.google.com/web/tools/lighthouse/)), look into two plugins: `gatsby-plugin-manifest` and `gatsby-plugin-offline`.
-5.  I did end up [deploying with Netlify](/docs/deploying-to-netlify), and I'm super happy with it. (A [previous post](/blog/2017-12-06-gatsby-plus-contentful-plus-netlify/#solution-netlify--gatsby) discussed Netlify a bit more, if you're interested).
+1. You [don't need to know GraphQL](https://github.com/gatsbyjs/gatsby/issues/1172#issuecomment-308634739) to get started with Gatsby. I didn't. It's been a good introduction.
+2. Gatsby makes heavy use of [plugins](/docs/plugins/) — both official and community — for a lot of things, from one that implements [Google Analytics](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-plugin-google-analytics), to one that adds [GitHub's accessibility error scanner](https://github.com/alampros/gatsby-plugin-accessibilityjs) to all pages.
+3. Read through some of the source code. I particularly enjoyed reading through [the bootstrap process](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby/src/bootstrap/index.js). (It's beautifully commented).
+4. Gatsby.js is a static Progressive Web App (PWA) generator, but to be PWA friendly (at least according to the [Lighthouse PWA audit](https://developers.google.com/web/tools/lighthouse/)), look into two plugins: `gatsby-plugin-manifest` and `gatsby-plugin-offline`.
+5. I did end up [deploying with Netlify](/docs/deploying-to-netlify), and I'm super happy with it. (A [previous post](/blog/2017-12-06-gatsby-plus-contentful-plus-netlify/#solution-netlify--gatsby) discussed Netlify a bit more, if you're interested).
diff --git a/docs/blog/2018-03-07-why-we-created-the-plugin-library/index.md b/docs/blog/2018-03-07-why-we-created-the-plugin-library/index.md
@@ -23,10 +23,10 @@ This map reflects how it took most people a lot of time browsing through the plu
 
 With the empathy map and the interviews as our guide, we learned that most people want to:
 
-1.  Find the best, most recent, and relevant plugin, library, or component for their site.
-2.  Learn how to build a plugin.
-3.  Preview plugin functionality before installation.
-4.  Share plugins with others.
+1. Find the best, most recent, and relevant plugin, library, or component for their site.
+2. Learn how to build a plugin.
+3. Preview plugin functionality before installation.
+4. Share plugins with others.
 
 ## Learning from other plugin libraries
 

diff --git a/docs/blog/2018-04-11-trying-out-gatsby-at-work-and-co/index.md b/docs/blog/2018-04-11-trying-out-gatsby-at-work-and-co/index.md
@@ -103,7 +103,7 @@ We ran into one schematic limitation working with Gatsby that’s helpful to be
 
 The are some really promising discussions on the topic on GitHub, including an [RFC to refactor Gatsby’s schema generation](https://github.com/gatsbyjs/gatsby/issues/4261), but in the meantime, most users are getting around this issue by creating placeholder content on Contentful (or whatever their data source is) to guarantee a fully built-up schema.
 
-This got the job done in our case, and we augmented the approach by creating a `DummyContentIndex` model on Contentful linking to all placeholder content. (In retrospect, I wish I had picked the a more PC name, like ‘PlaceholderContentIndex` 😉.) Using this approach, we could inform our Contentful scripts to make sure placeholder content was copied to the production environment during deploys, so that new models would not break the build.
+This got the job done in our case, and we augmented the approach by creating a `DummyContentIndex` model on Contentful linking to all placeholder content. (In retrospect, I wish I had picked the a more PC name, like `PlaceholderContentIndex` 😉.) Using this approach, we could inform our Contentful scripts to make sure placeholder content was copied to the production environment during deploys, so that new models would not break the build.
 
 ### Netlify