docs(www): 25 Workflows - Embedding components in Markdown with MDX #14543

gillkyle · 2019-06-04T21:58:00Z

Description

Clarifies and updates examples for the workflow of a new user adding components to their markdown content with MDX.

Main things changed:

some examples were outdated and were thus updated, with additional code snippets included to really spell out how to use different techniques for people new to MDX
some headers and structure was adjusted to more clearly state the intent of a given section
broken links were updated, and some additional links added to help explain more technical concepts

Related Issues

Addresses #14258 as part of the effort of the 25 Workflows improvements

…explanations

marcysutton

Looking good! I had a few suggestions, but it's in really good shape otherwise. Thanks for working on this!

docs/docs/mdx/writing-pages.md

# Conflicts: # docs/docs/adding-markdown-pages.md # docs/docs/mdx/writing-pages.md

…om/gillkyle/gatsby into www/docs-workflow-markdown-and-mdx

amberleyromo

Now that MDX is stable, @ChristopherBiscardi moved gatsby-mdx to gatsby-plugin-mdx, so we should use gatsby-plugin-mdx from now on.

I stopped changing these, but in this whole section, gatsby-mdx needs to be replaced with gatsby-plugin-mdx.

Also I was thinking about the heading of this whole section:

Adding Components to Content with MDX

Make more sense as something like:

Adding JavaScript to Markdown with MDX

cc @marcysutton

docs/docs/mdx/getting-started.md

docs/docs/mdx/writing-pages.md

docs/docs/mdx/programmatically-creating-pages.md

marcysutton · 2019-06-17T23:08:06Z

docs/docs/mdx/writing-pages.md


-Similarly to what you'd do in JSX, you can import and render components
-with JSX. You can also import other MDX documents.
+## Importing JSX components and MDX documents


Should this be "Importing JSX components in MDX documents"?

I think the "and" is good because it shows that both can be imported rather than just React components. JSX components and MDX documents are able to be imported in an MDX file.

ok, we can leave as-is!

marcysutton

I recommend that we merge this PR and make incremental updates afterward. A lot of the remaining items are around integrating docs from other sites/adding redirects. It's best to keep this moving as we want to start communicating about gatsby-plugin-mdx in the Gatsby docs, and this is the start of that effort (thanks @amberleyromo for surfacing that info!).

One outstanding item was whether to rename "Adding Components to Content with MDX" – this is an ongoing discussion that we should continue beyond this PR!

johno

This is looking great! ✨

gillkyle · 2019-06-18T20:34:59Z

Sounds like the preferred route is merge this now and incrementally improve things like an MDX section in the Gatsby API.

I think that sounds great 👍

amberleyromo

merge this now and incrementally improve things like an MDX section in the Gatsby API

👍👍👍

docs/docs/mdx/index.md

marcysutton

Hey @gillkyle! I ended up making some suggestions for a landing page title change so we can close out that discussion while we're in here (the URL is all good). Thanks for your patience on this one!

docs/docs/mdx/index.md

www/src/data/sidebars/doc-links.yaml

Co-Authored-By: Marcy Sutton <marcy@gatsbyjs.com>

…om/gillkyle/gatsby into www/docs-workflow-markdown-and-mdx

Co-Authored-By: Marcy Sutton <marcy@gatsbyjs.com>

…om/gillkyle/gatsby into www/docs-workflow-markdown-and-mdx # Conflicts: # www/src/data/sidebars/doc-links.yaml

gillkyle · 2019-06-19T01:32:25Z

After like 10 weird merge conflicts from applying suggestions in weird orders and merging master all the titles now reflect "Adding Components to Markdown with MDX" 😅

marcysutton · 2019-06-19T04:12:37Z

This is so great. Thanks again for your work on it @gillkyle, and to @johno and @amberleyromo for reviews!

* master: (41 commits) chore(release): Publish fix(gatsby): Normalize paths for run queries before caching (#14910) chore(release): Publish fix(gatsby-cli): add missing node-fetch dependency (#14908) feat(blog): Site Showcase Validator blogpost (#14855) chore(gatsby-remark-graphviz): add --ignore for test directory (#14906) fix(tutorials): rename "advanced" to "additional (#14847) fix(starters): update gatsby monorepo (#14886) chore(starters): Switch to useStaticQuery (#14857) chore(release): Publish Add status bar to bottom of screen during develop (#14874) chore(release): Publish fix(*): fix gatsby-cli dep in source-filesystem & plugin-sharp (#14881) docs(www): 25 Workflows - Embedding components in Markdown with MDX (#14543) docs(blog): add case study blog post for The Couch / Prima (#14871) docs(www): 25 Workflows - Adding CSS and/or Sass (#14779) fix(gatsby-transformer-react-docgen): always create description nodes (#14876) chore(release): Publish chore(gatsby): revert progressbar functionality (#14884) Revised "winning over engineering leaders" Docs page (#14830) ...

…atsbyjs#14543) * chore: updates to docs to improve examples and provide more detailed explanations * fix: simple grammatcial changes * fix: PR review suggestions * fix: correct code block titles and update example inline jsx * Amberleys PR comments * feat: add mdx as a title to code blocks * add link to glossary for components to help disambiguate * Update docs/docs/mdx/index.md Co-Authored-By: Marcy Sutton <marcy@gatsbyjs.com> * Update docs/docs/mdx/index.md Co-Authored-By: Marcy Sutton <marcy@gatsbyjs.com> * Update www/src/data/sidebars/doc-links.yaml Co-Authored-By: Marcy Sutton <marcy@gatsbyjs.com> * local merge conflicts + github suggestions = confusion

gillkyle added 2 commits June 4, 2019 15:38

chore: updates to docs to improve examples and provide more detailed …

48bdb98

…explanations

Merge branch 'master' into www/docs-workflow-markdown-and-mdx

9bf56c4

gillkyle requested a review from a team June 4, 2019 21:58

gillkyle requested a review from a team as a code owner June 4, 2019 21:58

fix: simple grammatcial changes

021aca6

marcysutton suggested changes Jun 5, 2019

View reviewed changes

gillkyle added 6 commits June 5, 2019 09:26

fix: PR review suggestions

28d2c32

Merge branch 'master' into www/docs-workflow-markdown-and-mdx

10ea744

Merge branch 'master' into www/docs-workflow-markdown-and-mdx

cb8203b

# Conflicts: # docs/docs/adding-markdown-pages.md # docs/docs/mdx/writing-pages.md

Merge branch 'master' into www/docs-workflow-markdown-and-mdx

37d6d93

Merge branch 'www/docs-workflow-markdown-and-mdx' of https://github.c…

746d94d

…om/gillkyle/gatsby into www/docs-workflow-markdown-and-mdx

fix: correct code block titles and update example inline jsx

3ad4b4a

gillkyle requested a review from marcysutton June 10, 2019 15:32

gillkyle added status: awaiting reviewer response A pull request that is currently awaiting a reviewer's response type: documentation An issue or pull request for improving or updating Gatsby's documentation 🎯 Learning labels Jun 10, 2019

amberleyromo suggested changes Jun 14, 2019

View reviewed changes

gillkyle added 3 commits June 14, 2019 15:11

Amberleys PR comments

f086017

feat: add mdx as a title to code blocks

8126526

Merge branch 'master' into www/docs-workflow-markdown-and-mdx

5adb170

gillkyle requested a review from amberleyromo June 17, 2019 17:42

gillkyle changed the title ~~fix(docs): Embedding components in Markdown with MDX Workflow~~ docs(www): Embedding components in Markdown with MDX Workflow Jun 17, 2019

gillkyle changed the title ~~docs(www): Embedding components in Markdown with MDX Workflow~~ docs(www): Embedding components in Markdown with MD Jun 17, 2019

gillkyle changed the title ~~docs(www): Embedding components in Markdown with MD~~ docs(www): 25 Workflows - Embedding components in Markdown with MDX Jun 17, 2019

marcysutton reviewed Jun 17, 2019

View reviewed changes

docs/docs/mdx/programmatically-creating-pages.md Show resolved Hide resolved

marcysutton reviewed Jun 17, 2019

View reviewed changes

marcysutton previously approved these changes Jun 18, 2019

View reviewed changes

johno previously approved these changes Jun 18, 2019

View reviewed changes

add link to glossary for components to help disambiguate

5cb0d53

gillkyle dismissed stale reviews from johno and marcysutton via 5cb0d53 June 18, 2019 23:46

amberleyromo previously approved these changes Jun 18, 2019

View reviewed changes

marcysutton reviewed Jun 19, 2019

View reviewed changes

docs/docs/mdx/index.md Outdated Show resolved Hide resolved

marcysutton suggested changes Jun 19, 2019

View reviewed changes

docs/docs/mdx/index.md Outdated Show resolved Hide resolved

www/src/data/sidebars/doc-links.yaml Outdated Show resolved Hide resolved

gillkyle and others added 2 commits June 18, 2019 19:23

Merge branch 'master' into www/docs-workflow-markdown-and-mdx

ec059f9

Update docs/docs/mdx/index.md

0ebae5d

Co-Authored-By: Marcy Sutton <marcy@gatsbyjs.com>

gillkyle dismissed amberleyromo’s stale review via 0ebae5d June 19, 2019 01:25

gillkyle and others added 5 commits June 18, 2019 19:25

Merge branch 'www/docs-workflow-markdown-and-mdx' of https://github.c…

b916be3

…om/gillkyle/gatsby into www/docs-workflow-markdown-and-mdx

Update docs/docs/mdx/index.md

a63acda

Co-Authored-By: Marcy Sutton <marcy@gatsbyjs.com>

Update www/src/data/sidebars/doc-links.yaml

c766d9f

Co-Authored-By: Marcy Sutton <marcy@gatsbyjs.com>

Merge branch 'www/docs-workflow-markdown-and-mdx' of https://github.c…

6020a30

…om/gillkyle/gatsby into www/docs-workflow-markdown-and-mdx # Conflicts: # www/src/data/sidebars/doc-links.yaml

local merge conflicts + github suggestions = confusion

879d9ae

gillkyle requested a review from marcysutton June 19, 2019 01:32

marcysutton approved these changes Jun 19, 2019

View reviewed changes

marcysutton removed the status: awaiting reviewer response A pull request that is currently awaiting a reviewer's response label Jun 19, 2019

marcysutton merged commit df94c22 into gatsbyjs:master Jun 19, 2019

garethpbk mentioned this pull request Aug 27, 2019

chore(www): Fix link hash for frontmatter section of page #17123

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(www): 25 Workflows - Embedding components in Markdown with MDX #14543

docs(www): 25 Workflows - Embedding components in Markdown with MDX #14543

gillkyle commented Jun 4, 2019

marcysutton left a comment

amberleyromo left a comment

marcysutton Jun 17, 2019

gillkyle Jun 18, 2019

marcysutton Jun 18, 2019

marcysutton left a comment

johno left a comment

gillkyle commented Jun 18, 2019 •

edited

Loading

amberleyromo left a comment

marcysutton left a comment

gillkyle commented Jun 19, 2019

marcysutton commented Jun 19, 2019

docs(www): 25 Workflows - Embedding components in Markdown with MDX #14543

docs(www): 25 Workflows - Embedding components in Markdown with MDX #14543

Conversation

gillkyle commented Jun 4, 2019

Description

Related Issues

marcysutton left a comment

Choose a reason for hiding this comment

amberleyromo left a comment

Choose a reason for hiding this comment

marcysutton Jun 17, 2019

Choose a reason for hiding this comment

gillkyle Jun 18, 2019

Choose a reason for hiding this comment

marcysutton Jun 18, 2019

Choose a reason for hiding this comment

marcysutton left a comment

Choose a reason for hiding this comment

johno left a comment

Choose a reason for hiding this comment

gillkyle commented Jun 18, 2019 • edited Loading

amberleyromo left a comment

Choose a reason for hiding this comment

marcysutton left a comment

Choose a reason for hiding this comment

gillkyle commented Jun 19, 2019

marcysutton commented Jun 19, 2019

gillkyle commented Jun 18, 2019 •

edited

Loading