You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Let's start with markdown file. I'm assuming we all know markdown. There's a reason why it's so popular, the syntax is so clean.
1
+
Let's start with this markdown file. I'm assuming we all know markdown.
2
2
3
-
I'm sure I'm not the only one who wants to move as much content as possible to markdown, even content that doesn't originally belong to markdown. That's why we have MDX, right? We had to extend the original format so we could fit more types of content.
3
+
There's a reason why it's so popular, it has a very clean syntax.
4
4
5
-
In this talk, we'll take this to the extreme, and use MDX for more unusual content and layouts.
5
+
I'm sure I'm not the only one who likes to move as much content as possible to markdown, even content that doesn't originally belong to markdown.
6
+
7
+
And that's why we have MDX, right? We had to extend the original format so we could put more things on it.
8
+
9
+
In this talk, we'll take this to the extreme, we'll use MDX for more unusual content and layouts.
6
10
7
11
---
8
12
9
-
But first I need to show you how this works. So we are going to start with this small react app.
13
+
But first I need to show you how this works. We are going to start with this small react app.
10
14
11
15
This is using Next.js but the same applies to any app that has the MDX loader.
12
16
13
17
---
14
18
15
-
Most of the magic comes from this import. Here the MDX loader transforms the markdown file into a React component that we can use anywhere. And, as expected, it renders what you can see here on the right.
19
+
Most of the magic comes from this import.
20
+
21
+
Here the MDX loader transforms the markdown file into a React component that we can use anywhere.
22
+
23
+
And, you can see, it renders what you expect here on the right.
16
24
17
25
---
18
26
19
-
If we want to change what's rendered, we can use the MDXProvider component. It has a components prop, that let us override any of the default components.
27
+
If we want to change what's rendered, we can use the MDXProvider component.
28
+
29
+
It has a components prop, that let us override any of the default components.
20
30
21
31
For example, here we are changing all the h1s, adding a purple border.
22
32
23
33
---
24
34
25
-
A special component we can override is the Wrapper. The wrapper is the component that wraps the content. Here we are just adding a border to it. But the cool thing about this component, is that, in the children prop, we get all the content from the markdown file as React elements .
35
+
A special component we can override is the Wrapper.
36
+
37
+
The wrapper is the component that wraps the content. Here we are just adding a border to it.
38
+
39
+
But the cool thing about this component is that in the children prop, we get all the content from the markdown file as React elements.
26
40
27
41
---
28
42
29
-
And React elements are just javascript objects. So here we are rendering the wrapper children as JSON, and filtering some properties to make it easier to read.
43
+
And React elements are just javascript objects.
44
+
45
+
So here you can see what's inside the children prop.
46
+
47
+
We are rendering the wrapper children as JSON, and filtering some properties to make it easier to read.
30
48
31
-
You'll see that it is an array. The first element is an h1, the second a paragraph. Each element comes with an mdxType prop, we can use that type to extract information about the content or to change the elements.
49
+
You'll see that it is an array. The first element is an h1, the second a paragraph.
50
+
51
+
Each element comes with an mdxType, we can, and we will, use that mdxType to extract information about the content or to change the elements.
32
52
33
53
---
34
54
35
-
For example we could get a list of all the H1s from the children, and render that list as a table of contents, before rendering the actual content.
55
+
For example, we could get a list of all the H1s from the children, and render it as a table of contents.
56
+
57
+
This is a simple example, but it illustrates the pattern we are going to use on the rest of the examples.
36
58
37
-
This is a simple example, but it illustrates the pattern we are going to use on the rest of the examples from this talk. First we extract some data from the children, and then we render it in a specific way.
59
+
In all of them, first, we extract some data from the children, and then we render it in a specific way.
38
60
39
-
Keep in mind that this runs on every render. For most cases, it isn't a performance problem, but if it is, you can move it to a plugin, and run the transformation on build-time.
61
+
Keep in mind that this runs on every render. In most cases, it isn't a performance problem, but if it is, you can move it to a plugin, and run the transformation on build-time.
40
62
41
63
---
42
64
43
65
I usually write content that has steps, like tutorials or any type of walkthrough where you explain something step by step.
44
66
45
-
Markdown doesn't have any specific syntax for grouping things in steps. But we can use MDX to extend markdown and introduce our own syntax. The implementation of the Step component we are using here doesn't matter, we are just using it for grouping elements.
67
+
Markdown doesn't have any specific syntax for grouping things in steps. But we can use MDX to extend markdown and introduce our syntax.
68
+
69
+
The implementation of the Step component we are using here doesn't matter, we are just using it for grouping elements.
46
70
47
-
If you are new to MDX, this may not be the best introduction. The typical use-case for MDX is embeding interactive components in markdown. But here we are taking a different approach, and using it more as a syntax extension for markdown.
71
+
If you are new to MDX, this may not be the best introduction. The typical use-case for MDX is embedding interactive components in markdown. But here we are taking a different approach, and using it more as a syntax extension for markdown.
48
72
49
73
---
50
74
51
-
Now, based on the MDX file that has steps, we can write another Wrapper component. In this case, in the children prop, we get one React element for each step.
75
+
Now, based on the MDX file that has steps, we can write another Wrapper component.
76
+
77
+
In this case, in the children prop, we get one React element for each step.
52
78
53
79
So we can keep track of what step we are showing using React state, and let the user change the current step with a button.
54
80
55
81
-> click
56
82
57
83
-> click
58
84
59
-
Ok, now I want to show the same content but with different layout. There's a technique called scrollytelling. You may have seen it on some websites, as the user scrolls down there's some part of the layout that sticks to the screen while the rest is scrolled away. Let's do that.
85
+
Ok, now I want to show the same content but with a different layout.
86
+
87
+
There's a technique called scrollytelling. You may have seen it on some websites, as the user scrolls down there's some part of the layout that sticks to the screen while the rest is scrolled away. Let's do that.
60
88
61
89
---
62
90
@@ -78,11 +106,13 @@ Now, instead of showing the step number, let's add the sticker content to the MD
78
106
79
107
---
80
108
81
-
Suppose we want to show some code in the sticky part of the layout. There isn't any specific syntax for this, so we need to create our own convention. Like, for example, we put the sticky part of the step as the first element.
109
+
Suppose we want to show some code in the sticky part of the layout.
110
+
111
+
There isn't any specific syntax for this, so we need to create our convention. Like, for example, we put the sticky part of the step as the first element.
82
112
83
113
---
84
114
85
-
Now doing some array transformation, we get the list of steps and the list of stickers and pass them to the same Layout component.
115
+
Now, doing some array transformation, we get the list of steps and the list of stickers and pass them to the same Layout component.
86
116
87
117
So when the user scrolls
88
118
@@ -92,11 +122,13 @@ the code on the right
92
122
93
123
--> scrolls
94
124
95
-
should change accordingly
125
+
should change accordingly.
96
126
97
127
---
98
128
99
-
Just for fun, I have a Terminal component that animates between code transitions, so we can use for the stickers.
129
+
Just for fun, I have a Terminal component that animates between code transitions,
130
+
131
+
so we can use it for the stickers.
100
132
101
133
--> scrolls
102
134
@@ -106,17 +138,21 @@ Just for fun, I have a Terminal component that animates between code transitions
106
138
107
139
--> scrolls 0
108
140
109
-
I've been experimenting with another layout for walkthroughs, instead of changing the steps using the scroll like in this example, we can synchronize the steps with some media, like a video or an audio, maybe a podcast, and change the steps as the media progress.
141
+
I've been experimenting with another layout for walkthroughs,
142
+
instead of changing the steps using the scroll like in this example,
143
+
we can synchronize the steps with some media, like a video or audio, maybe a podcast, and change the steps as the media progress.
110
144
111
145
---
112
146
113
147
To do that, in the MDX file, we need to specify the media file and the time range for each step.
114
148
115
149
---
116
150
117
-
Once we have that, we can extract it from the children on the Wrapper, and pass it to another React component. This time is the TalkLayout component, that solves all the synching for us.
151
+
Once we have that, we can extract it from the children on the Wrapper, and pass it to another React component.
118
152
119
-
And the steps should change every time I snap the fingers.
153
+
This time is the TalkLayout component, that solves all the synching for us.
154
+
155
+
And you should see the steps changing every time I snap the fingers.
120
156
121
157
--> snap 1
122
158
@@ -130,18 +166,21 @@ And it is.
130
166
131
167
This talk was built using this same technique. It's all MDX.
132
168
133
-
For example, here on the left you can see the code for the step you are currently watching.
169
+
For example, here on the left, you can see the code for the step you are currently watching.
134
170
135
171
---
136
172
137
173
And the next step.
138
174
139
175
---
140
176
141
-
Ok, that's all. The talk's takeaway is: you can use MDX to build your own dialect tailored for any specific layuout.
177
+
Ok, that's all.
178
+
179
+
The takeaway is: you can use MDX to build your own dialect tailored for any specific layout.
142
180
143
181
I leave you here the links to the repo of the talk. Not the slides, but the talk itself. You run yarn dev and you can watch this talk again.
144
182
145
-
Also there's my twitter, and the components we used, most of them come from a new project I'm working on, it's called Code Hike and it focuses on code walkthroughs and tools for making it easy to explain code.
183
+
Also, there's my twitter, and the components we used.
184
+
Most of them come from a new project I'm working on, it's called Code Hike and it focuses on code walkthroughs and tools for making it easy to explain code.
0 commit comments