From 78628cd48386e3ee7664be5bbcc20a00cb9a64f9 Mon Sep 17 00:00:00 2001
From: Pedr Browne <pedr.browne@gmail.com>
Date: Mon, 7 May 2018 16:59:26 +0100
Subject: [PATCH 1/2] Expand docs for custom components

The docs for custom components only mention defining custom components in the markdown, but don't address one of the most useful aspects - that you can map generic markdown tags/elements to your own components. I've expanded the docs to point this out and added a simple example.
---
 .../2018-01-27---custom-components/index.md   | 35 ++++++++++++++++++-
 1 file changed, 34 insertions(+), 1 deletion(-)

diff --git a/examples/using-remark/src/pages/2018-01-27---custom-components/index.md b/examples/using-remark/src/pages/2018-01-27---custom-components/index.md
index 4223d3637a570..4393a613eb552 100644
--- a/examples/using-remark/src/pages/2018-01-27---custom-components/index.md
+++ b/examples/using-remark/src/pages/2018-01-27---custom-components/index.md
@@ -11,7 +11,7 @@ tags:
 
 What if you want custom UI interactions embedded in your Markdown?
 
-By using `rehype-react` with the `htmlAst` field, you can write custom React components and then reference them from your Markdown files.
+By using `rehype-react` with the `htmlAst` field, you can write custom React components and then reference them from your Markdown files, or map generic HTML elements like `<ul>` or `<h2>` to your own components. 
 
 _Note: this functionality was added in version 1.7.31 of gatsby-transformer-remark_
 
@@ -143,6 +143,39 @@ In addition, you can also pass attributes, which can be used as props in your co
 
 <interactive-counter initialvalue="10"></interactive-counter>
 
+## Mapping from generic HTML elements
+
+You can also map a generic HTML element to one of your own components. This can be particularly useful if you are using something like styled-components as it allows you to share these primatives between markdown content and the rest of your site. It also means the author of the Markdown doesn't need to use any custom markup - just standard markdown.
+
+For example if you have a series of header components:
+
+```javascript
+const PrimaryTitle = styled.h1`…`
+const SecondaryTitle styled.h2`…`
+const TertiaryTitle styled.h3`…`
+```
+
+You can map headers defined in markdown to these components:
+
+```js
+const renderAst = new rehypeReact({
+  createElement: React.createElement,
+  components: { 
+    "h1": PrimaryTitle,
+    "h2": SecondaryTitle,
+    "h3": TertiaryTitle,
+   },
+}).Compiler;
+```
+
+And headers defined in markdown will be rendered as your components instead of generic HTML elements:
+
+```markdown
+# This will be rendered as a PrimaryTitle component
+## This will be rendered as a SecondaryTitle component
+### This will be rendered as a TertiaryTitle component
+```
+
 ## Caveats
 
 Although it looks like we're now using React components in our Markdown files, that's not _entirely_ true: we're adding custom HTML elements which are then replaced by React components. This means there are a few things to watch out for.

From 95469f414e2fb78485b62d0f9757cb181dbeb300 Mon Sep 17 00:00:00 2001
From: Mike Allanson <michael.allanson@gmail.com>
Date: Tue, 8 May 2018 10:26:54 +0100
Subject: [PATCH 2/2] Typo

---
 .../src/pages/2018-01-27---custom-components/index.md           | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/examples/using-remark/src/pages/2018-01-27---custom-components/index.md b/examples/using-remark/src/pages/2018-01-27---custom-components/index.md
index 4393a613eb552..9035f1a7bd4e1 100644
--- a/examples/using-remark/src/pages/2018-01-27---custom-components/index.md
+++ b/examples/using-remark/src/pages/2018-01-27---custom-components/index.md
@@ -145,7 +145,7 @@ In addition, you can also pass attributes, which can be used as props in your co
 
 ## Mapping from generic HTML elements
 
-You can also map a generic HTML element to one of your own components. This can be particularly useful if you are using something like styled-components as it allows you to share these primatives between markdown content and the rest of your site. It also means the author of the Markdown doesn't need to use any custom markup - just standard markdown.
+You can also map a generic HTML element to one of your own components. This can be particularly useful if you are using something like styled-components as it allows you to share these primitives between markdown content and the rest of your site. It also means the author of the Markdown doesn't need to use any custom markup - just standard markdown.
 
 For example if you have a series of header components: