MDX-DECK-README.md

Advanced MDX-deck

In this example we will be deploying an mdx-deck presentation which will also contain:

• Images that we want to be available offline
• Custom MDX-deck layouts
• Code snippets that we want to be available offline
• A custom Codesurfer React component to navigate code snippets

Getting started with Advanced MDX-deck

A sample presentation has been created at demo-advanced.mdx

Deploy with Now

First we need to create a now.json configuration file to instruct Now how to build the project.

For this example we will be using our newest version Now 2.0.

By adding the version key to the now.json file, we can specify which Now Platform version to use.

We also need to define how the project will be built. In this case, we will use the @now/mdx-deck Builder.

Builders are modules that take a deployment's source and return an output, consisting of either static files or dynamic Lambdas.

In this case we are going to use @now/static-build to build and deploy our static application selecting the package.json as our entry point. We will also define a name for our project (optional).

If we take a look at our demo presentation demo-advanced.mdx we will see that we are loading images and code snippets.

As an added bonus, if you look at line forty-three (43) of demo-advanced.mdx there is a custom React component that allows the presenter to identify and highlight specific lines from the example code snippet:

<CodeSurfer
  code={require("!raw-loader!./snippets/example-dockerfile.snippet")}
  title="Dockerfile for photo-share-api"
  showNumbers
  steps={[
    {}, // First step should be an overview of the snippet
    {lines: [1], notes: "Specify the base Node.js image"},
    {range: [6,7], notes: "Create the working directory on our process"},
    {range: [9,11], notes: "Copy and install our dependencies just like we would locally"},
    {range: [13,14], notes: "Copy our application code over"},
    {lines: [15], notes: "What is this? It seems a little...unusual."},
    {range: [17,19], notes: "We need to define ports for Docker to access"},
    {range: [21,22], notes: "This is the command to start our back-end server"},
    {}
  ]}
/>

// Special thanks to https://elijahmanor.com/code-surfer/ for this custom component

We must update our now.json file by adding a routes key to handle this. Our default route / will serve up the index.html page generated through the mdx-deck build process. We are also adding additional routes /images and /snippets for additional assets we are including with the presentation.

{
  "version": 2,
  "name": "mdx-deck-advanced",
  "builds": [
    {"src": "package.json", "use": "@now/static-build"}
  ],
  "routes": [
    { "src": "^/images/(.*)", "dest": "/images/$1" },
    { "src": "^/snippets/(.*)", "dest": "/snippets/$1" },
    { "src": "index.html", "dest": "/index.html" }
  ]
}

Visit our documentation for more information on the now.json configuration file.

We also need to include a script in package.json named "now-build" that specifies what command Now will run on the server to "build" your application.

By default, MDX-deck will output the build to the dist directory. We also need to explicitly copy folders containing our images and our snippets to the dist folder.

{
    "scripts": {
        ...
        "now-build": "mdx-deck build demo-advanced.mdx --no-html && cp -r images dist/ && cp -r snippets dist/"
    }
}

We are now ready to deploy the app.

now

---

Setting up a new deck

Template for Creating a new Deck

• Copy folder - decks/_empty_deck_template
• Give new name
• Edit package.json of deck

Update the JSON with deck name

{
    "private": true,
    "name": "empty-deck-template", // change name
    "version": "1.0.0",
    "scripts": {
     // can stay the same
    }
  }

Configure Now deployment

Edit root now.json to include build for new deck:

  { "version": 2,
  "name": "mdx-deck-advanced",
  "builds": [
   // ...
    {
      "src": "decks/your-new-deck/package.json",
      "use": "@now/static-build"
    }
  ]
}

Include in "Master Deck" if you want

// /deck.js
import intro from './intro.mdx'
// ...
import yourNewDeck from './decks/yourNewDeck';

export { default as theme } from './theme'

export default [
    ...intro,
 // ...
    ...yourNewDeck
]

Run Deck in Isolation

yarn workspace nameYouGaveInPackage packageServeCommand

Run Master Deck

yarn run serve

misc notes

Format

• Will have some talking to concepts/slides
  • Slides will cover high level points
  • Will be 'talked to' more than read
  • Typically followed by live+coding some examples to explore the concept
  • Can answer questions people have during this time,
  • Can also code examples as part of answering questions
• Other sections will have some exercises / examples setup
  • will use various online tools such as
    • repl.it
    • codesandbox
    • stackblitz
• Will aim for most large sections to have a larger exercise to work with
  • Will have initial online enviornment setup
  • Some initial code
  • Clear instructions / Requirements
• For Days 3 & 4
  • Will have basic setup of an application
  • Set of features to be built out that will leverage the concepts taught
  • Features can have 'stretch goals'
    • Allow for basic implementation
    • Allow for room for refactoring, or usage of more advanced patterns
• Link to Slides / Material will be provided before hand
  • Slides will contain teaching Material
  • Links to online tools
  • Links to other useful learning / reading resources that cover topics more in depth