[examples/using-remark]: Custom React components in Markdown files (#…

…3732)

examples/using-remark/package.json

@@ -29,6 +29,7 @@
  "lodash-id": "^0.14.0",
  "lodash-webpack-plugin": "^0.11.2",
  "react-typography": "^0.15.10",
+ "rehype-react": "^3.0.2",
  "slash": "^1.0.0",
  "typeface-space-mono": "^0.0.22",
  "typeface-spectral": "^0.0.29",

examples/using-remark/src/components/Counter.js

@@ -0,0 +1,47 @@
+import React from "react"
+
+const counterStyle = {
+ display: `flex`,
+ flexFlow: `row nowrap`,
+ alignItems: `center`,
+ padding: `0.2em 0.4em`,
+ borderRadius: `2px`,
+ backgroundColor: `rgba(0, 0, 0, 0.2)`,
+ boxShadow: `inset 2px 1.5px 4px rgba(0, 0, 0, 0.2)`,
+}
+
+export default class Counter extends React.Component {
+ static defaultProps = {
+ initialvalue: 0,
+ }
+
+ state = {
+ value: Number(this.props.initialvalue),
+ }
+
+ handleIncrement = () => {
+ this.setState(state => {
+ return {
+ value: state.value + 1,
+ }
+ })
+ }
+
+ handleDecrement = () => {
+ this.setState(state => {
+ return {
+ value: state.value - 1,
+ }
+ })
+ }
+
+ render() {
+ return (
+ <span style={counterStyle}>
+ <strong style={{ flex: `1 1` }}>{this.state.value}</strong>
+ <button onClick={this.handleDecrement}>-1</button>
+ <button onClick={this.handleIncrement}>+1</button>
+ </span>
+ )
+ }
+}

examples/using-remark/src/pages/2018-01-27---custom-components/index.md

@@ -0,0 +1,181 @@
+---
+title: "Custom components"
+date: "2018-01-27"
+draft: false
+author: Jay Gatsby
+tags:
+ - remark
+ - React
+ - components
+---
+
+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.
+
+## Writing a component
+
+Write the component the way you normally would. For example, here's a simple "Counter" component:
+
+```js
+import React from "react"
+
+const counterStyle = {
+ /* styles skipped for brevity */
+}
+
+export default class Counter extends React.Component {
+ static defaultProps = {
+ initialvalue: 0,
+ }
+
+ state = {
+ value: Number(this.props.initialvalue),
+ }
+
+ handleIncrement = () => {
+ this.setState(state => {
+ return {
+ value: state.value + 1,
+ }
+ })
+ }
+
+ handleDecrement = () => {
+ this.setState(state => {
+ return {
+ value: state.value - 1,
+ }
+ })
+ }
+
+ render() {
+ return (
+ <span style={counterStyle}>
+ <strong style={{ flex: `1 1` }}>
+ {this.state.value}
+ </strong>
+ <button onClick={this.handleDecrement}>-1</button>
+ <button onClick={this.handleIncrement}>+1</button>
+ </span>
+ )
+ }
+}
+
+```
+
+## Enabling the component
+
+In order to display this component within a Markdown file, you'll need to add a reference to the component in the template that renders your Markdown content. There are five parts to this:
+
+1. Install `rehype-react` as a dependency
+
+ ```bash
+ # If you use Yarn
+ yarn add rehype-react
+
+ # If you use npm
+ npm install --save rehype-react
+ ```
+
+2. Import `rehype-react` and whichever components you wish to use
+
+ ```js
+ import rehypeReact from "rehype-react"
+ import Counter from "../components/Counter"
+ ```
+
+3. Create a render function with references to your custom components
+
+ ```js
+ const renderAst = new rehypeReact({
+ createElement: React.createElement,
+ components: { "interactive-counter": Counter },
+ }).Compiler
+ ```
+
+ I prefer to use hyphenated names to make it clear that it's a custom component.
+
+4. Render your content using `htmlAst` instead of `html`
+
+ This will look different depending on how you were previously referring to the post object retrieved from GraphQL, but in general you'll want to replace this:
+
+ ```js
+ <div dangerouslySetInnerHTML={{ __html: post.html }} />
+ ```
+
+ with this:
+
+ ```js
+ {renderAst(post.htmlAst)}
+ ```
+
+5. Change `html` to `htmlAst` in your `pageQuery`
+
+ ```graphql
+ # ...
+ markdownRemark(fields: { slug: { eq: $slug } }) {
+ htmlAst # previously `html`
+
+ # other fields...
+ }
+ # ...
+ ```
+
+## Using the component
+
+Now, you can directly use your custom component within your Markdown files! For instance, if you include the tag:
+
+```html
+<interactive-counter></interactive-counter>
+```
+
+You'll end up with an interactive component:
+
+<interactive-counter></interactive-counter>
+
+In addition, you can also pass attributes, which can be used as props in your component:
+
+```html
+<interactive-counter initialvalue="10"></interactive-counter>
+```
+
+<interactive-counter initialvalue="10"></interactive-counter>
+
+## 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.
+
+### Always add closing tags
+
+JSX allows us to write self-closing tags, such as `<my-component />`. However, the HTML parser would incorrectly interpret this as an opening tag, and be unable to find a closing tag. For this reason, tags written in Markdown files always need to be explicitly closed, even when empty:
+
+```html
+<my-component></my-component>
+```
+
+### Attribute names are always lowercased
+
+HTML attribute names are not case-sensitive. `gatsby-transformer-remark` handles this by lowercasing all attribute names; this means that any props on an exposed component must also be all-lowercase.
+
+> The prop in the `Counter` example above was named `initialvalue` rather than `initialValue` for exactly this reason; if we tried to access `this.props.initialValue` we'd have found it to be `undefined`.
+
+### Attributes are always strings
+
+Any prop that gets its value from an attribute will always receive a string value. Your component is responsible for properly deserializing passed values.
+
+- Numbers are always passed as strings, even if the attribute is written without quotes: `<my-component value=37></my-component>` will still receive the string `"37"` as its value instead of the number `37`.
+- React lets you pass a prop without a value, and will interpret it to mean `true`; for example, if you write `<MyComponent isEnabled />` then the props would be `{ isEnabled: true }`. However, in your Markdown, an attribute without a value will not be interpreted as `true`; instead, it will be passed as the empty string `""`. Similarly, passing `somevalue=true` and `othervalue=false` will result in the string values `"true"` and `"false"`, respectively.
+- You can pass object values if you use `JSON.parse()` in your component to get the value out; just remember to enclose the value in single quotes to ensure it is parsed correctly (e.g. `<my-thing objectvalue='{"foo": "bar"}'></my-thing>`).
+
+> Notice in the `Counter` example how the initial `value` has been cast using the `Number()` function.
+
+## Possibilities
+
+Custom components embedded in Markdown enables many features that weren't possible before; here are some ideas, starting simple and getting complex:
+
+- Write a live countdown clock for an event such as Christmas, the Super Bowl, or someone's birthday. Suggested markup: `<countdown-clock> 2019-01-02T05:00:00.000Z </countdown-clock>`
+- Write a component that displays as a link with an informative hovercard. For example, you might want to write `<hover-card subject="ostrich"> ostriches </hover-card>` to show a link that lets you hover to get information on ostriches.
+- If your Gatsby site is for vacation photos, you might write a component that allows you to show a carousel of pictures, and perhaps a map that shows where each photo was taken.
+- Write a component that lets you add live code demos in your Markdown, using [component-playground](https://formidable.com/open-source/component-playground/) or something similar.
+- Write a component that wraps a [GFM table](./hello-world-kitchen-sink/#tables) and displays the data from the table in an interactive graph.

examples/using-remark/src/templates/template-blog-post.js

@@ -1,13 +1,20 @@
 import React from "react"
 import Link from "gatsby-link"
 import Img from "gatsby-image"
+import rehypeReact from "rehype-react"
 
 import styles from "../styles"
 import { rhythm, scale } from "../utils/typography"
 import presets from "../utils/presets"
+import Counter from "../components/Counter"
 
 import "katex/dist/katex.min.css"
 
+const renderAst = new rehypeReact({
+ createElement: React.createElement,
+ components: { "interactive-counter": Counter },
+}).Compiler
+
 class BlogPostRoute extends React.Component {
  render() {
  const post = this.props.data.markdownRemark
@@ -69,7 +76,7 @@ class BlogPostRoute extends React.Component {
  className="toc"
  />
 
- <div dangerouslySetInnerHTML={{ __html: post.html }} className="post" />
+ {renderAst(post.htmlAst)}
  <hr
  css={{
  marginBottom: rhythm(1),
@@ -122,7 +129,7 @@ export default BlogPostRoute
 export const pageQuery = graphql`
  query BlogPostBySlug($slug: String!) {
  markdownRemark(fields: { slug: { eq: $slug } }) {
- html
+ htmlAst
  timeToRead
  tableOfContents
  fields {