Slideck

Gem Version Actions CI Build status Maintainability Coverage Status

Terminal tool for presenting Markdown-powered slide decks.

Features

  • Write slides in the Markdown with extended syntax.
  • Show code snippets in fenced code blocks.
  • Syntax highlight code for over 200 languages.
  • Create Markdown tables with advanced formatting.
  • Align slide content with familiar CSS syntax.
  • Add margin around content for all or a single slide.
  • Track progress through the slides with a pager.
  • Display a footer at the bottom of every slide.
  • Apply custom symbols and style theme to content.
  • Auto reload presentation when a file with slides changes.

Installation

Slideck will work with any version of Ruby greater than or equal to 2.0. Read Installing Ruby guide to choose the best installation method.

Once Ruby is set up, install the slideck with:

$ gem install slideck

Contents

1. Usage

Open a text file and start writing slides in Markdown. Begin the document by adding configuration for all slides in YAML format. Then to denote a slide, separate its content with three dashes. Use the same configuration settings to override the global settings for a slide. To do so, specify settings with YAML flow mappings after the slide separator.

Here's a sample of a few slides with global and slide-specific configuration settings:

align: center
margin: 2 5
footer:
  align: center bottom
  text: Footer content

--- margin: 0

# Welcome to Slideck

## Built with TTY Toolkit

--- align: center top

# Code Block

```ruby
puts "Welcome to Slideck"
```

--- theme: {list: magenta}

# Unordered List

- Item 1
- Item 2
- Item 3

--- symbols: ascii

# Table

| A | B | C |
|---|---|---|
| a | b | c |
| a | b | c |
| a | b | c |

--- {pager: false, footer: false}

# The End

To start presenting, for example, slides.md file in a terminal:

$ slideck slides.md

Use the -h or --help flag to see help about available presentation controls and options:

$ slideck --help

Use the -w or --watch flag to automatically reload the presentation with any update to the slides.md file:

$ slideck slides.md --watch

2. Configuration

Configuration options can be global or slide-specific.

Add global configuration options in YAML format at the beginning of a document.

For example, to configure alignment and margin for all slides:

align: center
margin: 2 5

---

First Slide

---

Second Slide

---

Use YAML flow mappings syntax to change the global configuration for a given slide. This format is a series of key/value pairs separated by commas and surrounded by curly braces. The semicolon with space follows a key and splits it from value. Braces are optional for a single key/value pair. A slide-specific configuration follows three dashes and needs to be on the same line.

For example, to override alignment and margin for a given slide:

align: center
margin: 2 5

--- margin: 0

First Slide

--- {align: center top, margin: 1 3}

Second Slide

---

2.1 Align

Slideck draws the slide's content from the left top of the terminal screen by default. It positions the pager at the bottom right corner. When given, the footer ends up at the bottom left corner. Use the :align configuration to change the default positioning of content, footer and pager.

The align configuration takes either one or two values. The first value specifies the horizontal alignment out of left, center and right. The second value describes vertical alignment out of the top, center and bottom. Skipping the second value will default the vertical alignment to the center. Use a space, comma or both to separate two values.

For example, to position content at the top center of the screen on every slide:

align: center top

Or use shorthand to place content at the center left on every slide:

align: left

Use the same configuration to change the alignment for a single slide. It needs to follow after the slide separator and be on the same line.

For example, to place a given slide at the bottom left:

--- align: left bottom

Slideck doesn't show the footer by default. Use the :footer configuration to add content to the bottom left of the screen for every slide.

For example, to display a footer on every slide:

footer: Footer content

The footer supports Markdown syntax:

footer: **bold** content

The footer can also span more than one line:

footer: "first line\nsecond line\nthird line"

Use the :align key to change the footer alignment and the :text key to specify its content.

For example, to specify a global footer at the bottom center of every slide:

footer:
  align: center bottom
  text: Footer content

Use the same configuration to change the footer for a single slide. It needs to follow after the slide separator and be on the same line.

For example, to place a footer at the bottom center of the screen:

--- footer: {align: center bottom, text: Footer content}

Or, use a false value to hide a footer for a single slide:

--- footer: false

2.3 Margin

The margin specifies a distance from all four sides of the terminal screen. It follows CSS rules and can have one, two, three or four integer values. Use a space or comma to separate each integer value.

The following are all possible ways to specify a margin:

margin: 1         # the same margin of 1 for all sides
margin: 1 2       # 1 to the top and bottom, and 2 to the left and right
margin: 1 2 3     # 1 to the top, 2 to the left and right, and 3 to the bottom
margin: 1 2 3 4   # 1 to the top, 2 to the right, 3 to the bottom, 4 to the left

Or, specify a margin with explicit side names:

margin:
  top: 1
  right: 2
  bottom: 3
  left: 4

Like shorthand notation, specify names only for the configured sides.

For example, to add only the top margin and leave all the other sides with their default values:

margin:
  top: 1

Use the same configuration to change the margin for a single slide. It needs to follow after the slide separator and be on the same line.

For example, to zero out the margin for a given slide:

--- margin: 0

2.4 Pager

Slideck displays the pager in the bottom right corner of the terminal screen. The display format is %<page>d / %<total>d, where the first placeholder represents the current slide and the second is the total number of slides.

For example, to change the pager display:

pager: "Page %<page>d of %<total>d"

The pager supports Markdown syntax:

pager: "**Bold** %<total> pages"

The pager can also span more than one line:

pager: "Page\n%<page>d\nof\n%<total>d"

Use the :align key to change the pager alignment and the :text key to specify its content.

For example, to place the pager at the bottom center of every slide:

pager:
  align: center bottom
  text: "Page %<page>d of %<total>d"

Or, use a false value to hide a pager on all slides:

pager: false

Use the same configuration to change the pager for a single slide. It needs to follow after the slide separator and be on the same line.

For example, to place a pager at the bottom center of a given slide:

--- pager: {align: center bottom, text: "Page %<page>d of %<total>d"}

Or, use a false value to hide a pager for a single slide:

--- pager: false

2.5 Symbols

Slideck decorates Markdown elements with unicode symbols by default. Use the :symbols configuration to change the display of decorative characters. It takes either a single value or key/value pairs. The single value specifies a character set out of ascii or unicode. The key/value pairs accept the :base and :override keys. Like a single value, the :base key takes either ascii or unicode.

For example, to change the default symbols for all slides to ascii:

symbols: ascii

Or, use the :base key to specify the ascii character set:

symbols:
  base: ascii

The :override key accepts key/value pairs, where the key is a symbol name and the value is a decorative character. Please see the tty-markdown for a complete list of symbols.

For example, to change the :bullet symbol for every slide:

symbols:
  override:
    bullet: x

Use the same configuration to change the symbols for a single slide. It needs to follow after the slide separator and be on the same line.

For example, to change a character set to ascii for a single slide:

--- symbols: ascii

Or, to change the :bullet symbol for a single slide:

--- symbols: {override: {bullet: x}}

2.6 Theme

Slideck displays Markdown elements with a default style theme. Use the :theme configuration to change individual element styles. It takes key/value pairs where the key is the element name, and the value is a single style or list of styles. Please see the tty-markdown for a complete list of element names and their styles.

For example, to change em, link and list element styles for every slide:

theme:
  em: blue
  link: cyan
  list: magenta

Use the same configuration to change the theme for a single slide. It needs to follow after the slide separator and be on the same line.

For example, to change em, link and list element styles for a single slide:

--- theme: {em: blue, link: cyan, list: magenta}

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/piotrmurach/slideck. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

The gem is available as open source under the terms of the GNU Affero General Public License v3.0.

Code of Conduct

Everyone interacting in the Slideck project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.

Copyright (c) 2022 Piotr Murach. See LICENSE.txt for further details.