[docs]Docs/Blog Frontmatter Documentation

docs/contributing/docs-and-blog-components.md

@@ -206,6 +206,90 @@ New docs and blog posts are added to the [docs](https://github.com/gatsbyjs/gats
 
 You can read more about writing in Markdown in the [Markdown syntax guide](/docs/mdx/markdown-syntax).
 
+### Frontmatter
+
+[Frontmatter](/docs/adding-markdown-pages/#frontmatter-for-metadata-in-markdown-files) is a set of key value pairs that are injected into when building Markdown and MDX files. While authoring new docs and blog posts, it may be helpful to understand what frontmatter is available to you and how Gatsby expects it to be used.
+
+#### General
+
+- `title` (string)
+
+  The title of the doc or blog post. Gatsby renders the value in `og:title`, `<title>` and `<h1>`.
+
+- `excerpt` (string)
+
+  The excerpt for the post. Gatsby renders the value in `description`, `og:description`, and `twitter:description`.
+
+#### Blog Posts
+
+- `date` (string)
+
+  The blog post's date. GraphQL converts the string to a Date object and renders it with the format `MMMM Do YYYY`.
+
+- `canonicalLink` (string)
+
+  The canonical link. Gatsby renders the value in `<link rel="canonical">`.
+
+- `tags` (array)
+
+  The blog post's related tags. Gatsby renders the [YAML array/list](https://en.wikipedia.org/wiki/YAML#Basic_components) as links to tag archives and creates the archive if it doesn't exist.
+
+- `image` (string)
+
+  The relative path to the image.
+
+  - Facebook and `twitterCard: summary` support an aspect ratio of 1:1.
+  - LinkedIn supports an aspect ratio of 1.91:1 and `twitterCard: summary_large_image` supports an aspect ratio of 2:1
+  - Gatsby resizes the image to 1500x1500 and renders the URL in the `og:image` and `twitter:image` metadata.
+  - If `showImageInArticle` is true, Gatsby renders an image with the width of 786px in the hero of the blog post.
+
+- `imageAuthor` (string)
+
+  The name of the image's author. Gatsby renders the value in an `<a>` tag only if `imageAuthorLink` is defined.
+
+- `imageAuthorLink` (string)
+
+  The link to the image's author. Gatsby renders the value in an `<a>` tag only if `imageAuthor` is defined.
+
+- `showImageInArticle` (boolean, default false)
+
+  Determines if the `image` is displayed as a hero in the blog post.
+
+- `twitterCard` (string)
+
+  A choice between: `summary` or `summary_large_image` that Gatsby renders in the `twitter:card` metadata.
+
+  - `summary` - The Summary Card can be used for many kinds of web content, from blog posts and news articles, to products and restaurants. It is designed to give the reader a preview of the content before clicking through to your website.
+  - `summary_large_image` - The Summary Card with Large Image features a large, full-width prominent image alongside a tweet. It is designed to give the reader a rich photo experience, and clicking on the image brings the user to your website.
+
+- `author` (string)
+
+  The author's name, which is also the `id` in the `/docs/blog/author.yaml` file. Gatsby renders a link to the author's archive page.
+
+#### Documentation
+
+- `description` (string, default `excerpt`)
+
+  A description of the doc. Gatsby renders the value in the `description` and `og:description` metadata.
+
+- `issue` (string)
+
+  The issue URL relating to a stub on GitHub. Gatsby renders a link to the stub.
+
+- `disableTableOfContents` - (boolean)
+
+  Determines if the table of contents is output.
+
+- `tableOfContentsDepth` - (integer)
+
+  The number of levels to render the table of contents.
+
+#### Relevant Links
+
+- [About Twitter Cards](https://developer.twitter.com/en/docs/tweets/optimize-with-cards/overview/abouts-cards)
+- [Facebook Sharing - Best Practices](https://developers.facebook.com/docs/sharing/best-practices#images)
+- [Making Your Website Shareable on LinkedIn](https://www.linkedin.com/help/linkedin/answer/46687/making-your-website-shareable-on-linkedin?lang=en)
+
 ### Code blocks
 
 Code can be formatted using regular Markdown syntax, but the docs site has additional enhancements that can be used thanks to various Gatsby plugins that aren't all native Markdown.