Scroll, Zoom, and Highlight code in a mdx-deck slide presentation with Code Surfer <🏄/>

Instructor: [00:00] If you have npm version 6.1 or above, then you could use the new initializer feature and create a MDX deck with npm init deck, and then the name of your new project. We'll call it my-code.

[00:14] This will map the initializer to a package named create-deck, which will be temporarily installed with npx. Once it's downloaded, it'll bootstrap our app and install all the necessary dependencies.

[00:27] Now, we'll switch to our new directory and install the code-surfer package that we'll use to highlight, zoom, and scroll our code snippets, and we'll install the raw-loader for webpack that will allow us to easily require code snippets from disk, and we'll make these dev dependencies. Once everything is installed, let's kick up VS Code and start poking around.

[00:47] There's already a pretty basic deck MDX file provided for us, which is a combination of JSX and Markdown. Let's kick up a dev server with npm start. It'll launch a browser for us, and we can navigate the basic three-slide presentation using the keyboard.

[01:03] We'll gut out most of the slide deck so that we could focus on the code-surfer component. First, let's import code-surfer from mdx-deck-code-surfer. Then we'll use the code-surfer component. Here, we'll provide some example code to render, console.log ("Hello, World!"). When saved, it'll automatically show up in our browser.

[01:27] Next, let's grab a snippet from the React website, and create a snippets folder and make a file called one.snippet that contains the code that we just copied. We could replace the static console.log and require the contents from our snippet file.

[01:46] To do this, we'll use the webpack raw-loader that we installed earlier, and reference the one.snippet file. Voila, the content show up in the browser. Next, let's try some props of the code-surfer component.

[02:00] We'll start with the title prop, which shows up at the top of the slide. Then we'll try the notes prop, which shows up at the bottom of the slide. These are the initial notes that will show up when the component first renders. We could also turn on line numbers if we choose to do so.

[02:19] The steps prop is where things start to get interesting. When giving a presentation with code displayed, it's beneficial if you could help the audience focus on one or more lines of code instead of showing a whole bunch at once.

[02:32] With code-surfer, we could specify what line to highlight, and give a note providing more detail about that line. In this case, we'll just say line. On the right, sure enough, the line is given a focus while the rest of the code fades away.

[02:48] We could also highlight multiple lines just by adding them to the array, like so, and will update the note to say lines. Sure enough, lines four, five, and six are highlighted.

[03:00] If you need several lines in sequence highlighted, it'd be somewhat annoying to type them all. Thankfully, there is a range option that we could use instead. In this case, the result is the same as manually giving lines four, five, and six.

[03:13] You could also provide multiple ranges in case you wanted to show off different snippets of code that aren't next to each other.

[03:23] Sometimes, you may want to highlight a portion of a line, and not the whole line itself. Code-surfer has a feature for that, too, called tokens. You could provide a line number as an object key, and then an array of tokens from within that line to highlight. Here, I'm focusing on the second and sixth tokens of the first line, which ends up highlighting hello, message, and React.

[03:49] This seems to work great and all with a relatively small snippet of code, but how does it behave with larger chunks of code? Let's find out.

[03:57] We'll grab another code snippet from the React website, but this time something longer. We'll paste that into another file and update code-surfer to reference it. The cool part hasn't happened yet.

[04:14] Let's navigate backwards through the steps to the beginning, and voila. Code-surfer zooms out to give a high-level view of the code, along with the initial notes. Then as you proceed through the steps, it zooms back in, focusing on each step separately.

[04:30] The last feature I'd like to highlight is what happens when lines, ranges, or tokens are out of range of what is currently viewed. Let's add a step that highlights lines 30 through 33. When the step is triggered, the slide will auto-scroll to the appropriate location to show the desired lines. Regardless if it needs to scroll up or down, it'll make sure it's within view for the audience to see.

[04:56] If you have a presentation coming up, or if you need to present some documentation, code-surfer is a powerful way to navigate and explain snippets of code.