Code Surfer

Rad code slides

Syntax highlightingReactPresentation
pomber/code-surfercodesurfer.pomb.us/mdx-deck-code-surfer

README


demo

Code Surfer


Help to keep this project alive with your support ❤️


Code Surfer adds code highlighting, code zooming, code scrolling, code focusing, code morphing, and fun to MDX Deck slides.

To create a new project run:

  1. ```bash
  2. npm init code-surfer-deck my-deck
  3. cd my-deck
  4. npm start
  5. ```

Examples


- Formidable's GraphQL Workshop by Phil Pluckthun
- React Conf 2018 Hooks Demo

How to use Code Surfer


It may help to know how MDX Deck works first


To use Code Surfer you need to import it and wrap the code you want to show inside `` tags (the **empty lines before and after the codeblock are required**):

  1. ````md
  2. import { CodeSurfer } from "code-surfer"

  4. # Deck Title

  6. ---

  8. <CodeSurfer>

  10. ```js
console.log(1);
console.log(2);
console.log(3);
  1. ```

  3. </CodeSurfer>
  4. ````

Features:

- Focus
- Steps
- Title and Subtitle
- Themes
- Custom Styles
- Languages
- Columns
- Import Code
- Line Numbers
- Diffs

Here is a live deck using all the features (and its mdx source) just in case you prefer to read code instead of docs.


Focus


Add a _focus string_ after the language in the first line of a codeblock to tell Code Surfer what lines and columns you want to focus.

Code Surfer will fade out all the code that isn't focused and, if necessary, zoom it out to fit it in the slide.

  1. ````md
  2. <CodeSurfer>

  4. ```js 1:2,3[8:10]
console.log(1);
console.log(2);
console.log(3);
  1. ```

  3. </CodeSurfer>
  4. ````

In the example above 1:2,3[8:10] means: "focus from the line 1 to line 2 and the columns 8 to 10 from line 3". More examples:

- 5:10 focus lines 5,6,7,8,9 and 10
- 1,3:5,7 focus lines 1,3,4,5 and 7
- 2[5] focus column 5 in line 2
- 2[5:8] focus columns 5, 6, 7 and 8 in line 2
- 1,2[1,3:5,7],3 focus line 1, columns 1, 3, 4, 5 and 7 in line 2 and line 3

_Note: In previous versions of CodeSurfer we used tokens instead of columns._

Steps


Add more codeblocks to add steps to a Code Surfer slide.

  1. ````md
  2. <CodeSurfer>

  4. ```js
console.log(1);
console.log(2);
console.log(3);
  1. ```

  3. ```js 1
console.log(1);
console.log(2);
console.log(3);
  1. ```

  3. ```js
console.log(1);
console.log(2);
console.log(3);
console.log(4);
console.log(5);
  1. ```

  3. </CodeSurfer>
  4. ````

You can change the focus and/or the code for different steps and Code Surfer will make the transition between the steps: zooming, scrolling, fading in, fading out, adding and removing lines.

Title and Subtitle


  1. ````md
  2. <CodeSurfer>

  4. ```js 1 title="Title" subtitle="Look at the first line"
console.log(1);
console.log(2);
console.log(3);
  1. ```

  3. ```js 2 title="Title" subtitle="and now the second"
console.log(1);
console.log(2);
console.log(3);
  1. ```

  3. </CodeSurfer>
  4. ````

Themes

Code Surfer Themes

There are many Code Surfer themes available on the [@code-surfer/themes](https://github.com/pomber/code-surfer/blob/code-surfer-v2/packs/themes/src/index.ts) package.

You can pass the theme as a prop ``:

  1. ````md
  2. import { CodeSurfer } from "code-surfer"
  3. import { nightOwl } from "@code-surfer/themes"

  5. <CodeSurfer theme={nightOwl}>

  7. ```js
console.log(1);
console.log(2);
console.log(3);
  1. ```

  3. </CodeSurfer>
  4. ````

Or set the theme for the whole deck as any other MDX Deck theme:

  1. ````md
  2. import { CodeSurfer } from "code-surfer"
  3. import { nightOwl } from "@code-surfer/themes"

  5. export const theme = nightOwl

  7. <CodeSurfer>

  9. ```js
console.log(1);
console.log(2);
console.log(3);
  1. ```

  3. </CodeSurfer>
  4. ````

Exporting the theme like this will also change the text and background colors for slides that aren't using Code Surfer. If you want to keep the colors from a different mdx deck theme you can compose both themes together:export const themes = [codeSurferTheme, mdxDeckTheme]


Custom Styles


You can write your own Code Surfer theme and change the style of the code, title and subtitle:

Themes use Theme UI internally


  1. ```js
  2. // custom-theme.js
  3. export default {
  4.   colors: {
  5.     background: "#222",
  6.     text: "#ddd",
  7.     primary: "#a66"
  8.   },
  9.   styles: {
  10.     CodeSurfer: {
  11.       pre: {
  12.         color: "text",
  13.         backgroundColor: "background"
  14.       },
  15.       code: {
  16.         color: "text",
  17.         backgroundColor: "background"
  18.       },
  19.       tokens: {
  20.         "comment cdata doctype": {
  21.           fontStyle: "italic"
  22.         },
  23.         "builtin changed keyword punctuation operator tag deleted string attr-value char number inserted": {
  24.           color: "primary"
  25.         },
  26.         "line-number": {
  27.           opacity: 0.8
  28.         }
  29.       },
  30.       title: {
  31.         backgroundColor: "background",
  32.         color: "text"
  33.       },
  34.       subtitle: {
  35.         color: "#d6deeb",
  36.         backgroundColor: "rgba(10,10,10,0.9)"
  37.       },
  38.       unfocused: {
  39.         // only the opacity of unfocused code can be changed
  40.         opacity: 0.1
  41.       }
  42.     }
  43.   }
  44. };
  45. ```

And use it in your deck like any other theme:

  1. ````md
  2. import { CodeSurfer } from "code-surfer"
  3. import customTheme from "./custom-theme"

  5. <CodeSurfer theme={customTheme}>

  7. ```js
console.log(1);
console.log(2);
console.log(3);
  1. ```

  3. </CodeSurfer>
  4. ````

Languages


Code Surfer uses Prism for parsing different languages, so it supports all the languages supported by Prism.

Most popular languages are supported out of the box, for the rest you need to import them:

  1. ````md
  2. import { CodeSurfer } from "code-surfer"
  3. import "prismjs/components/prism-smalltalk"

  5. <CodeSurfer>

  7. ```smalltalk
result := a > b
    ifTrue:[ 'greater' ]
    ifFalse:[ 'less or equal' ]
  1. ```

  3. </CodeSurfer>
  4. ````

Columns


If you want to show more than one piece of code at the same time, use ``:

  1. ````md
  2. import { CodeSurferColumns, Step } from "code-surfer"

  4. <CodeSurferColumns>
  5. <Step subtitle="First Step">

  7. ```js
console.log(1);
console.log(2);
  1. ```

  3. ```js
console.log("a");
console.log("b");
  1. ```

  3. </Step>
  4. <Step subtitle="Second Step">

  6. ```js 2
console.log(1);
console.log(2);
  1. ```

  3. ```js 2
console.log("a");
console.log("b");
  1. ```

  3. </Step>
  4. </CodeSurferColumns>
  5. ````

Each `` can have its own `title` and `subtitle`.

You can use different themes for each column: ``. And change the relative size of the columns with ``.

Columns aren't only for code, you can use them for any kind of content:

  1. ````md
  2. import { CodeSurferColumns, Step } from "code-surfer"
  3. import MyComponent from "./my-component.jsx"

  5. <CodeSurferColumns>
  6. <Step>

  8. ```js
console.log(1);
console.log(2);
  1. ```

  3. # Some Markdown

  5. </Step>
  6. <Step>

  8. ```js 2
console.log(1);
console.log(2);
  1. ```

  3. <MyComponent/>
  4. </Step>
  5. </CodeSurferColumns>
  6. ````

Import Code


Instead of writing the code inside codeblocks you can import it from a file:

  1. ````md
  2. import { CodeSurfer } from "code-surfer"

  4. <CodeSurfer>

  6. ```js 5:10 file=./my-code.js
  1. ```

  3. ```js file=./my-other-code.js
  1. ```

  3. </CodeSurfer>
  4. ````

Line Numbers


To show line numbers add the showNumbers flag to the first step:

  1. ````md
  2. import { CodeSurfer } from "code-surfer"

  4. <CodeSurfer>

  6. ```js showNumbers
console.log(1);
console.log(2);
console.log(3);
  1. ```

  3. ```js
console.log(1);
console.log(2);
console.log(4);
  1. ```

  3. </CodeSurfer>
  4. ````

Diffs


Codeblocks can also be diffs. This is particularly useful when using empty diffs for code that doesn't change:

  1. ````md
  2. import { CodeSurfer } from "code-surfer"

  4. <CodeSurfer>

  6. ```js
console.log(1);
console.log(2);
console.log(3);
  1. ```

  3. ```diff 1 subtitle="log 1"

  1. ```

  3. ```diff 2 subtitle="log 2"

  1. ```

  3. ```diff 3 subtitle="log 3"

  1. ```

  3. </CodeSurfer>
  4. ````

Related


- MDX Deck
- spectacle-code-slide
- Prism
- create-code-surfer-deck
- Gatsby Waves

Support Code Surfer


You can help keep this project alive.

Sponsors


Support this project by becoming a sponsor. Your logo will show up here with a link to your website. [Become a sponsor]


Backers


Thank you to all our backers! 🙏 [Become a backer]


Contributors


This project exists thanks to all the people who contribute.