Personal Site Playgrounds with MDX

Prince Wilson: [0:01] Hey, everyone. I hope you're enjoying MDX Conf. I'm Prince Wilson. I tried to come up with a short bio to describe who I am, and I came up with three main talking points.

[0:12] I work for a company called Newsela in New York City, where our primary focus is around creating educational content around current events that students from all across the country are able to understand and get informed about.

[0:25] I also love talking about learning, and maybe that's why I joined Newsela. I love being able to facilitate learning and also just the science around learning. I like knowing more and how our brains work and why we do the things that we do. Lastly, I love Corgis. I just thought you should know that. None of these topics are what I'm going to talk to you about today.

[0:47] In fact, I'm going to be talking about personal sites and how they are our personal playgrounds. A lot of the time, we see them as just like pieces towards showcasing our portfolio, or they need to be these pristine pieces of work that we put out onto the Internet.

[1:02] In reality, they can also be the places where we experiment. They don't have to be the things that we put out into production code, but they can also just be things that highlight the things that we're learning about.

[1:11] That's what I see my personal site is mostly. It's this thing that I can just play around with. I can build up a beautiful sandcastle, and if I decided I don't like it anymore, I can throw it away, too.

[1:23] Here's a little bit of a history around my blog. It started off with just like HTML files, just to showcase, "Hi, I'm Prince. You can reach me at these different places." That was great, but I wanted to find a way to archive my knowledge and that's why I moved to a static site generator known as Jekyll. That's powered by Ruby, as well as YAML.

[1:43] That worked really well, but I couldn't do as many interactive things like I wanted to, and that's what led me to going to Gatsby + MDX. The thing between each of these things is that I wanted to be able to do something more.

[1:55] The question of, "What more can I do?" was always the thematic thing. Is there something that could be done a little bit easier for me? Is there a new thing I could be putting in? Is there a thing that helps me author the content easier? That's been the biggest reasons why I keep moving to new pieces of technology.

[2:14] Today, I'm going to talk through one piece of my code that helped me. Like, think about how do I create more interactive things into my site? That's my Code Blocks. The code that you see in here isn't code that we're going to be talking about, but more so just to showcase how the CodeBlock looks on my site.

[2:33] It's powered by a tool called prism-react-renderer, made by FormidableLabs. FormidableLabs has a bunch of different libraries out there, but this one helps you build Code Blocks and is powered by React.

[2:44] Here's a primary example of how to use their CodeBlock generator, which is a lot of code to look at. Don't get me wrong. What I'm going to do is I'm going to simplify it down a little bit. You'll notice that I took care of all the stuff that's between the component Highlight. It just says, "Handle how to print out lines." We'll come back to that.

[3:07] The things that we should be focusing on are the exampleCode, as well as the line 8 where it says code={exampleCode} language="jsx". Those are the things that we're going to need to change out. That's where we're going to use MDX to power and help us with.

[3:23] Let's look at what happens when I take our CodeBlock and power it up with MDX. Given that MDX will give us a bunch of props when we connect it to our MDX provider, we'll be able to replace line 5 and line 9.

[3:40] In line 5, you'll notice I do some destructuring and pull out the children, the className, and the metastring. Those are the props that we're going to get from MDX. Those are going to tell my code on line 9, for instance, what's going to be pass at Highlight is the children. That's the actual code text that I want.

[3:58] The language is from the className, which is found on line 6. I take that className, I take off the prefix, and that's going to tell my CodeBlock how to generate. That's how it's all put together to make it look like this. This is like the base styles as well.

[4:15] If we want to get a little bit different, we can also add some presets themes that exists out there. For instance, prism-react-renderer offer us a few set of themes under their libraries such as nightOwl that you can pass in through a prop called theme.

[4:30] If you already had a theme, though, you can also pass in a custom theme by telling that theme prop that's undefined and then adding the required CSS to something like your Gatsby browser.

[4:42] Sara recently just published a tool that lets you convert your VSCode Theme into something that you can pass into prism.js or prism-react-renderer. I highly recommend, if you like your VSCode Theme, go ahead and do that.

[4:57] While that is almost everything I wanted, there is one thing that was missing out of the box from prism-react-renderer and that was line highlighting. This is a custom piece of functionality, but this helps me, and I know it helps other people recognize how to focus on particular parts of a CodeBlock.

[5:15] When I'm thinking about my content, I want to highlight areas that I want them to focus in the context of them being used as well. This is what it would look like in MDX, to do that CodeBlock stuff.

[5:27] You'll notice on line 1 that I have the language I'm using, JavaScript, as well as {1,3}. That's going to tell my CodeBlock which lines to highlight within the CodeBlock. That's powered by what is known as the metastring, that last little prop that we didn't get to talk about.

[5:49] That string is everything that's passed that JavaScript or the language that I specify inside of a CodeBlock. That's what all that power is. You can do a lot in there. Today, I'm going to talk about how I use it to calculate the lines to highlight.

[6:04] This is the function that I used to do the calculations to doing the line highlighting. It looks like a lot. Primarily, what it does is it checks whether or not there's a range of numbers that I want to be highlighting. If there are, it's going to do some work. If there's not, it's going to return false for us. It's going to be like, "Nope, you don't need to do anything."

[6:25] Once again, if we need to, it's going to calculate the range, and then pass out a function that determines whether or not this is the particular line that we need to be highlighting. This is a way to encapsulate all of the behaviors that we want. That way, we can use them back inside of our Highlight component.

[6:43] You might remember, that Highlight component, I took a bunch of stuff out. What we're going to now do is look at what all that bunch of stuff is. This is what it looks like. It's a function. It's going to return a bunch of stuff for us.

[6:57] On the first line, we're going to see the className, the style, the tokens, the getLineProps, the getTokenProps. This is all from the example already. One method that we need to pay attention to that's passed in as an argument is that getLineProps. That's what's going to tell our component, "This is the line that we need to be highlighting."

[7:15] We need to pass in the styles that we want to use to highlight as well. You'll see here, as I make my getLineProps, I pass in the line, the key that I'm in -- that's to tell the traditional key prop that we use in React -- but the last one is the style, which is the styles that I want to be passing if I need to highlight this line. That's what powers my line highlighting.

[7:40] You can pass in whatever styles that you want. If you want to highlight them differently, you tell it what to highlight as. It makes it work. Really, this was an opportunity for me to explore, how do I do more with my CodeBlocks? I think that's really what it is, is blogs are a place for exploration. I want to be able to say, "This is something I can experiment with."

[8:01] Here's some other experiments that I've also been looking at and trying to do while working on my blog site. One of them was being able to write something that lets me change all my CodeBlocks at once on my site.

[8:14] There's been a lot of iterations from that. This is an opportunity for me to experiment with the context of, what would help a reader? Here's it sliding through. You can see it updating in real time. It doesn't update the line highlight, because I didn't do that part, but it's still an experiment. That's the point.

[8:32] In this other example, what I'm going to do is I'm going to showcase how to open a playground. This is going to open a CodeSandbox of exactly that same CodeBlock that I had in my blog post. All of the code is passed in. The user can go in, then take the component that was writing, and use that.

[8:55] To me, that's really cool because of the fact that I can give you a working example and tell you what parts to throw in without having to make you go and look at the CodeSandbox immediately. I can make that all happen in runtime. I don't need to go and prepare it for you.

[9:11] Another example of this is where I play around with some Rust. Rust Playground has an API that you can pass in all of the Rust code that you want to have in the actual view, and you can make it go and run it. This, for instance, happens to work out of the box. I think that's so cool.

[9:30] I want you to go forth and create your own sandcastles. I want you to feel inspired to go and share your knowledge with people. At the end of the day, this is your playground. You get to do as much as you want with it. Here's some of the more resources that I shared throughout the slides.

[9:46] One major shout I want to give to Carlos, who came up with a solution for line highlighting within prism-react-renderer. If it wasn't for them, I wouldn't have what I have today. I want to give them a major shout out. I hope that you enjoy the rest of MDX Conf.