Docs page on using custom components and data (and more broadly MDX) #89
Conversation
✅ Deploy Preview for spectacular-dragon-c1015c ready!
To edit notification comments on pull requests, go to your Netlify site settings. |
Add: - basic info about MDX - how to utilize `import` and `export` statements supported by MDX to import and define custom components and data - note about JS expressions
olayway
force-pushed
the
20-components-import-docs
branch
from
1f35cc3 to
f1dc37b
Compare
There was a problem hiding this comment.
Great job! 👏 I'm going to merge now.
One major question (to address going forward) is about whether we can locate our components in site/content vs in templates/default as per my one major comment:
🚩 where is the
componentsfolders? This is crucial info for someone following along (is it relative to theircontentdirectory or where?Atm it looks like this components folder is inside templates/default. Is there any way to import component relative to content folder or this file and have components in
site/content/componentsor similar? That would be much more realistic for end users who don't have access to templates/default.
|
|
||
| Let's see what exactly is MDX and what's so cool about it! | ||
|
|
||
| <Callout> |
There was a problem hiding this comment.
Soon we can replace this with obsidian style callouts!
There was a problem hiding this comment.
One major question (to address going forward) is about whether we can locate our components in
site/contentvs intemplates/defaultas per my one major comment
At the moment, having components inside /content folder doesn't work. It will throw an error related to having mixed content there. But maybe this can be set somehow in Contentlayer.
triangular_flag_on_post where is the
componentsfolders? This is crucial info for someone following along (is it relative to theircontentdirectory or where?
Totally agree, I'll make it more explicit.
|
|
||
| # MDX | ||
|
|
||
| Flowershow parses all of your Markdown files as MDX. This means you not only can write your content using good old Markdown, but also extend it with JSX, JavaScript expressions, and `import` and `export` statements. It's basically Markdown on steroids 😀💪! |
There was a problem hiding this comment.
Context: This page is excellent. Comments here are more suggestions unless flagged as otherwise with 🚩
Personally, I might add a tiny bit about why this is powerful. e.g. "What this means is you can enrich your content with the full power of javascript and modern web technologies. [maybe add an examples e.g. adding rich dynamic visualizations or embedding data tables ...]
|
|
||
| Flowershow parses all of your Markdown files as MDX. This means you not only can write your content using good old Markdown, but also extend it with JSX, JavaScript expressions, and `import` and `export` statements. It's basically Markdown on steroids 😀💪! | ||
|
|
||
| Let's see what exactly is MDX and what's so cool about it! |
There was a problem hiding this comment.
Love the tone: friendly and direct.
| Let's see what exactly is MDX and what's so cool about it! | ||
|
|
||
| <Callout> | ||
| A basic familiarity with JSX (React components) and JavaScript might be helpful to understand this chapter, but you can also learn by example and start by tweaking some of our code. Opening this page in your text editor side by side with the rendered version in your browser may also help. |
There was a problem hiding this comment.
🚩 Opening this page in your text editor => link this page to the source in github (?)
|
|
||
| ### JSX and custom components | ||
|
|
||
| JSX allows you to create components, that you can reuse across all of your markdown files. This is especially useful if you find yourself writing a lot of custom HTML in your Markdown, and/or you use the same HTML code parts and copy them again and again to different markdown pages. You soon may find it difficult to tell what a given part of HTML block is supposed to do. And what used to be e.g. your blog content ends up as a Markdown-HTML-CSS soup. On top of that, imagine if you wanted to make some changes to all these copies of HTML blocks, that you used many different pages 🤯. |
There was a problem hiding this comment.
yes ... and we can also create dynamic components i.e. do programming. I'd almost emphasize that more e.g. we can have a datatable component and pass data to it. or create a chart. These are things you just can't do at all in markdown.
|
|
||
| #### Importing components | ||
|
|
||
| To see this in action, let's create a React component in the `/components` folder: |
There was a problem hiding this comment.
🚩 where is the components folders? This is crucial info for someone following along (is it relative to their content directory or where?
Atm it looks like this components folder is inside templates/default. Is there any way to import component relative to content folder or this file and have components in site/content/components or similar? That would be much more realistic for end users who don't have access to templates/default.
There was a problem hiding this comment.
I agree with you and I've tried it before. I'll double-check it but I think there is an error related to having mixed content in the /content folder.
|
@rufuspollock thank you for the great suggestions! I've applied them and just need to double-check the issue re having components in the |
Don't merge
Closes #20
Changes:
/docs/mdx) about MDX, containing:importandexportstatements, JS expressions)/test/mdx-components) for components written in MDX (=not JSX components)Notes
I wasn't sure if we want to write documentation for MDX components as well so I've only tested if they work for now.