gatsby.webstackbuilders.com v0.1.0

Notes and TODOs

require('source-map-support').install()
require('ts-node').register({
  compilerOptions: {
    module: 'commonjs',
    target: 'es2017',
  },
})

Using these instead of v2:

"@mdx-js/mdx": "1.6.22", "@mdx-js/react": "1.6.22",

MDX Notes

Frontmatter is also available in props.pageContext.frontmatter and can be accessed in blocks of JSX in your MDX document:

<h1>{props.pageContext.frontmatter.title}</h1>

MDX Processing Architecture

The gatsby-plugin-mdx uses @mdx-js/mdx, which is a unified pipeline that is wrapped so that most users do not need to know about unified. The processor goes through these steps:

Parse MDX (serialized markdown with embedded JSX, ESM, and expressions) to `mdast` (markdown syntax tree)
Transform through remark (markdown ecosystem)
Transform `mdast` to `hast` (HTML syntax tree)
Transform through `rehype` (HTML ecosystem)
Transform `hast` to `esast` (JS syntax tree)
Do the work needed to get a component
Transform through r`e`cma (JS ecosystem)
Serialize `esast` as JavaScript

The input is MDX (serialized markdown with embedded JSX, ESM, and expressions). The markdown is parsed with micromark/micromark and the embedded JS with one of its extensions micromark/micromark-extension-mdxjs (which in turn uses acorn). Then syntax-tree/mdast-util-from-markdown and its extension syntax-tree/mdast-util-mdx are used to turn the results from the parser into a syntax tree: mdast.

Markdown is closest to the source format. This is where remark plugins come in. Typically, there shouldn’t be much going on here. But perhaps you want to support GFM (tables and such) or frontmatter? Then you can add a plugin here: remark-gfm or remark-frontmatter, respectively.

After markdown, we go to hast (HTML). This transformation is done by syntax-tree/mdast-util-to-hast. Wait, why, what does HTML have to do with it? Part of the reason is that we care about HTML semantics: we want to know that something is an , not whether it’s a link with a resource (text) or a reference to a defined link definition (text\n\nid: url). So an HTML AST is closer to where we want to go. Another reason is that there are many things folks need when they go MDX -> JS, markdown -> HTML, or even folks who only process their HTML -> HTML: use cases other than MDX. By having a single AST in these cases and writing a plugin that works on that AST, that plugin can supports all these use cases (for example, rehypejs/rehype-highlight for syntax highlighting or rehypejs/rehype-katex for math). So, this is where rehype plugins come in: most of the plugins, probably.

Then we go to JavaScript: esast (JS; an AST which is compatible with estree but looks a bit more like other unist ASTs). This transformation is done by syntax-tree/hast-util-to-estree. This is a new ecosystem that does not have utilities or plugins yet. But it’s where @mdx-js/mdx does its thing: where it adds imports/exports, where it compiles JSX away into _jsx() calls, and where it does the other cool things that it provides.

Finally, The output is serialized JavaScript. That final step is done by astring, a small and fast JS generator.

Configure MDX shortcodes and default layout

MDXProvider is setup in Shortcodes, but right now not used.

Packages to add

Use Changesets?

• @changesets/changelog-github
• @changesets/cli

Setup Cypress and Jest Testing

• react-test-renderer
• @testing-library/cypress
• @testing-library/jest-dom
• @testing-library/react
• cypress
• gatsby-cypress

Scripts to Add

"typecheck": "tsc --noEmit", "typecheck:ci": "tsc -p tsconfig.ci.json --noEmit", "tsc:compile": "tsc --project cypress/tsconfig.json", "tsc:compile:watch": "tsc --watch --project cypress/tsconfig.json",

Gatsby Plugins To Configure

• gatsby-plugin-breadcrumb

Breadcrumbs, two approaches for generation

• gatsby-plugin-canonical-urls

Only options are to set the site URL and strip query parameters, gives a link in head like so: <link rel="canonical" href="https://www.example.com/about-us/" />

• gatsby-plugin-excerpts

Allows specifying excerpts using a shortcode instead of automatically being extracted. Adds a snippet field to nodes to use instead of excerpt. Locate excerpts using CSS selectors. May not work with Gatsby v4.x - uses gatsby-remark-custom-blocks, which is is incompatible with gatsby-transformer-remark@^4.0.0 until an upstream dependency is upgraded to remark 13.

• gatsby-plugin-guess-js

Automatically download Google Analytics data and use this to create a model to predict which page a user is most likely to visit from a given page. Adds <link prefetch> for resources on pages the user is likely to visit. This means that as soon as a person visits your site, their browser will immediately start downloading in the background code and data for links they’ll likely click on.

• gatsby-plugin-mailchimp

Subscribe new email addresses to a Mailchimp email list.

• gatsby-plugin-prefetch-google-fonts

Download and prefetch Google Fonts. Can increase performance as opposed to loading webfonts from Google’s external stylesheet. Comparison to gatsby_omni_font_loader, which has asynchronous font loading, font loading listener, web and local font loading, and Flash Of Unstyled Text (FOUT) handling support?

• gatsby-plugin-robots-txt

Generate robots.txt on build.

• gatsby-plugin-scroll-reveal

Animate DOM elements on scroll.

• gatsby-plugin-social-cards

Automatically parses your posts and generates social cards for Twitter, Slack, Facebook and other sites.

• gatsby-plugin-typography

Use the typography.js library with minimal configuration. Is this already used by Theme UI?

Remark Plugins To Configure

• gatsby-remark-autolink-headers

Hovering over a heading in a Markdown file produces a visible, clickable anchor link.

• gatsby-remark-copy-linked-files

Copies local files linked to/from Markdown (.md|.markdown) files to the root directory (i.e., public folder).

• gatsby-remark-embed-video

Embed video in Markdown: YouTube, Vimeo, Twitch.

• gatsby-remark-reading-time

Adds a medium-like reading time estimate to your Gatsby remark posts. Not sure if this differs from the built-in readingTime field that's available.

• gatsby-remark-responsive-iframe

Wraps iframes or objects e.g. embedded YouTube videos within markdown files in a responsive elastic container with a fixed aspect ratio. This ensures that the iframe or object will scale proportionally and to the full width of its container.

• gatsby-remark-smartypants

Replaces “dumb” punctuation marks with “smart” punctuation marks using the retext-smartypants plugin.

• gatsby-remark-twitter

Embed Tweet and Moment cards in Gatsby markdown.

• remark-gfm

  Support for autolink literals, footnotes, strikethrough, tables, and task lists.

Chat Setup

• gatsby-plugin-chatwoot

Quickly add the Chatwoot live chat widget to your Gatsby site. Self hosted version, Facebook, Twitter, Instagram, and Slack channels (receive the Chatwoot messages in the #customer-conversations channel). Chatwoot is an open source customer engagement platform, an alternative to Intercom, Zendesk & Salesforce Service Cloud.

Setup Search

• gatsby-plugin-local-search

Setup Social Share

Existing plugins all seem like commercial services.