Codestar theme for Marp

Two-in-one solution for building and hosting our slide decks.

---

Contents:

• Features
• Usage
• Editing guidelines
• Development

---

Features

• A new design using our new Codestar design language
  • Rotating slide accent colors using the Codestar palette
  • Title cards with brutalist-inspired pure CSS backgrounds
• Syntax highlighting using the Codestar palette, with language labeling
• Multi-column slides
• Automatic builds and hosting
• Slide decks listing

Quick links:

• Check out the example slide deck here!
• Listing of all slide decks

---

Usage

• Requirements:

  • If you want to write your Markdown in VS Code with a live preview: Marp for VS Code
  • Or, if you want to run a live preview server: npm install -g @marp-team/marp-cli

• To get started, make a new directory for your slide deck and copy the example sldes (replace deck-name with the title of your presentation):

  mkdir decks/deck-name
  cp example.md decks/deck-name/slides.md

  Extra resource files (for example images or videos) can go in that new folder as well.

• Edit and preview your slides:

  • VS Code: open this repository's folder, edit the new slides.md file, and in the top right corner of the editor, click the preview button (or ⌘ + K, V).

  • marp-cli: from this repo's root, run marp -s --theme theme/codestar.css . to start a live server with a directory listing that you can navigate on http://localhost:8080.

• Make a pull request and merge. GitHub actions will build the slides and serve them on our decks listing hosted on GH pages.

---

Editing guidelines

Metadata

• Make sure to fill all the metadata in the front matter.

• Metadata directives can be changed for a particular slide. For example, if you want a different footer on one slide, include this:

  <!-- _footer: This slide has a different footer! -->

  If you want a slide without a footer or header, add:

  <!-- _header: '' -->
  <!-- _footer: '' -->

Customization

• Make sure to update the QR code's link by replacing example/ with the name of your slide deck's directory.
• If you prefer a dark theme, uncomment class: invert in the front matter.
• Presenter notes can be added using regular HTML comments, and will be visible on each slide when using the presenter mode.

Tip

To start presenter mode, move the mouse over the presentation and click the right button on the toolbar.

• To make a slide with multiple columns, use a <div> with the columns class:

  <div class="columns">
  <div>
  
  Column 1 markdown goes here
  
  </div><div>
  
  Column 2 markdown goes here
  
  </div>

Note

The number of columns is dynamic and unbounded. For an example, consult the example slides in example.md.

• To embed a video, make a standalone slide with the following tag in it:

  ---
  
  <video autoplay loop muted src="video.mp4"></video>
  
  ---

Note

The muted attribute is necessary for the autoplay to work (otherwise browsers block it to avoid spam). If you need sound, use <video controls src="video.mp4">

Warning

Make sure to produce clips that are not too big in size. You can search online for ffmpeg compression tips. The options -c:v libx264 -crf 23 -preset fast should be a good starting point.

Other guidelines

• Keep the div structure of the title card and the thank you slide intact.
• Keep section title cards short, with at most a subtitle.
• The casual tone of some slides can be changed to a more formal tone if preferred (for example, "any questions?" instead of "questions time").
• For reference on other formatting options, slide layouts, slide backgrounds, etc., check out all the slides from examples.md (you can also watch that presentation here).

Quick reference links:

• Image syntax
• Transitions
• Directives
• Supported emoji codes

---

Development

Requirements:

• The watch script needs fswatch to monitor SCSS changes:

  brew install fswatch

• Sass is needed for building the styles:

  npm install -g sass

• And for building the actual slides:

  npm install -g @marp-team/marp-cli

You can then run ./watch.sh to watch for changes in any SCSS file to rebuild the main CSS file.

Note

The output file theme/codestar.css is included in version control so that it can be hosted and used directly as a link to GitHub, but it is generated code and not meant for editing.