Fix/4459/excerpt formatting ignored

packages/gatsby-transformer-remark/README.md

@@ -81,7 +81,9 @@ Using the following GraphQL query you'll be able to get the table of contents
 
 By default the tableOfContents is using the field `slug` to generate URLs. You can however provide another field using the pathToSlugField parameter. **Note** that providing a non existing field will cause the result to be null.
 
-### Excerpt length
+### Excerpts
+
+#### Length
 
 By default, excerpts have a maximum length of 140 characters. You can change the default using the `pruneLength` argument. For example, if you need 500 characters, you can specify:
 
@@ -98,6 +100,36 @@ By default, excerpts have a maximum length of 140 characters. You can change the
 }
 ```
 
+#### Format
+
+By default, Gatsby will return excerpts as plain text. This might be useful for populating [opengraph](https://en.wikipedia.org/wiki/Facebook_Platform#Open_Graph_protocol) HTML tags for SEO reasons. You can also explicitly specify a `PLAIN` format like so:
+
+```graphql
+{
+  allMarkdownRemark {
+    edges {
+      node {
+        excerpt(format: PLAIN)
+      }
+    }
+  }
+}
+```
+
+It's also possible to ask Gatsby to return excerpts formatted as HTML. You might use this if you have a blog post whose an excerpt contains markdown content--e.g. header, link, etc.--and you want these links to render as HTML.
+
+```graphql
+{
+  allMarkdownRemark {
+    edges {
+      node {
+        excerpt(format: HTML)
+      }
+    }
+  }
+}
+```
+
 ## Troubleshooting
 
 ### Excerpts for non-latin languages

packages/gatsby-transformer-remark/src/__tests__/__snapshots__/extend-node.js.snap

@@ -55,6 +55,24 @@ Object {
 }
 `;
 
+exports[`Excerpt is generated correctly from schema given an html format, it correctly maps nested markdown to html 1`] = `
+Object {
+  "excerpt": "<p>Where oh <a><em>where</em></a> <strong><em>is</em></strong> that pony?</p>",
+  "frontmatter": Object {
+    "title": "my little pony",
+  },
+}
+`;
+
+exports[`Excerpt is generated correctly from schema given an html format, it respects the excerpt_separator 1`] = `
+Object {
+  "excerpt": "<p>Where oh where is that pony? Is he in the stable…</p>",
+  "frontmatter": Object {
+    "title": "my little pony",
+  },
+}
+`;
+
 exports[`Links are correctly prefixed correctly prefixes links 1`] = `
 Object {
   "html": "<p>This is <a href=\\"/prefix/path/to/page1\\">a link</a>.</p>

packages/gatsby-transformer-remark/src/__tests__/extend-node.js

@@ -237,6 +237,74 @@ In quis lectus sed eros efficitur luctus. Morbi tempor, nisl eget feugiat tincid
       expect(node.excerpt.length).toBe(50)
     }
   )
+
+  bootstrapTest(
+    `given an html format, it correctly maps nested markdown to html`,
+    `---
+title: "my little pony"
+date: "2017-09-18T23:19:51.246Z"
+---
+
+Where oh [*where*](nick.com) **_is_** that pony?`,
+    `excerpt(format: HTML)
+    frontmatter {
+        title
+    }
+    `,
+    node => {
+      expect(node).toMatchSnapshot()
+      expect(node.excerpt).toMatch(
+        `<p>Where oh <a><em>where</em></a> <strong><em>is</em></strong> that pony?</p>`
+      )
+    }
+  )
+
+  bootstrapTest(
+    `given an html format, it prunes large excerpts`,
+    `---
+title: "my little pony"
+date: "2017-09-18T23:19:51.246Z"
+---
+
+Where oh where is that pony? Is he in the stable or down by the stream?`,
+    `excerpt(format: HTML, pruneLength: 50)
+    frontmatter {
+        title
+    }
+    `,
+    node => {
+      // expect(node).toMatchSnapshot()
+      expect(node.excerpt).toMatch(
+        `<p>Where oh where is that pony? Is he in the stable…</p>`
+      )
+    }
+  )
+
+  bootstrapTest(
+    `given an html format, it respects the excerpt_separator`,
+    `---
+title: "my little pony"
+date: "2017-09-18T23:19:51.246Z"
+---
+
+Where oh where is that pony? Is he in the stable or by the stream?
+
+<!-- end -->
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi auctor sit amet velit id facilisis. Nulla viverra, eros at efficitur pulvinar, lectus orci accumsan nisi, eu blandit elit nulla nec lectus. Integer porttitor imperdiet sapien. Quisque in orci sed nisi consequat aliquam. Aenean id mollis nisi. Sed auctor odio id erat facilisis venenatis. Quisque posuere faucibus libero vel fringilla.
+`,
+    `excerpt(format: HTML, pruneLength: 50)
+    frontmatter {
+        title
+    }
+    `,
+    node => {
+      expect(node).toMatchSnapshot()
+      expect(node.excerpt).toMatch(
+        `<p>Where oh where is that pony? Is he in the stable…</p>`
+      )
+    },
+    { excerpt_separator: `<!-- end -->` }
+  )
 })
 
 describe(`Wordcount and timeToRead are generated correctly from schema`, () => {