Create your own markdown presentation theme for Slidium

custom markdown presentation theme

Writing themes for Slidium

One of the advantages of Slidium is to allow custom themes creation.

Some of the Slidium themes are open source. The sources can be found in our Github. You can freely modify them but keep the credit for the initial work.

We provide a starter kit containing :

  • A template of a JSON file
  • A thumbnail with the right dimensions
  • A "minimal" CSS file (in less)

General information about themes

  • Themes are in HTML. You can also use CSS and SVG. It is not recommended to use javascript in themes. To be honest, we do not see the need to use javascript but if you find such situation, please contact us to see together what can be done.
  • They should be at least supported by iOS 10/ Mac OS 1.12 (Sierra) You can use http://caniuse.com/ to ensure that the features you are using are properly supported. This, however, does not replace a final check on the right platform.
  • You should not only support iOS and Safari but also target all modern browsers if you want to export for the web presentations using your theme.
  • Flexbox is intensively used because it solves a lot of tricky layout configurations. However, it is not mandatory and you can provide your own system.
  • Your theme should Retina and HiDpi screens properly. Your different assets should hence provide a resolution high enough to display properly on these devices.
  • When possible, use images in SVG format instead of raster formats

Theme structure

  • Thumbnail: file has to be named theme.png In order to support properly retina displays, its dimensions need to be 300 pixels x 219 pixels
  • JSON
    • Name: Name of the theme: please make sure that the name is not yet used.
    • Author: Only informative
    • Version: Only informative
    • Description: Informative, describe the theme
    • Palets: mandatory, the list of color palets supported by the theme. See below for more details
    • Layouts: mandatory, the list of layouts provided by the them. See below for more information
    • HelpUrl: The URL where documentation and theme specific layouts can be found.
    • Template: This is the markdown code (including YAML) which will be used when creating a new presentation. You can use it
  • CSS
    • theme.css
  • Additional assets
    • Images
    • SVG files
    • Fonts (It is better to stick to system fonts. If however, you plan to use other fonts, make sure to provide them with the theme (check license))

Ratios / Presentation sizes

  • Even if Slidium only supports a single ratio for the moment (960 pixels x 700 pixels), themes have to be developed to be responsive and to adapt to different screen ratios.
  • Here are the standard ratios:
    • 960 pixels x 700 pixels
    • 1244 pixels x 700 pixels

Colors conventions

Depending on the theme, you can need to display the same content over a light or a dark background. We recommend to use for that purpose the two following CSS classes:

  • bg-dark in order to specify a dark background (requiring a light foreground)
  • bg-light (should be the default) in order to specify a light background.

These classes can be applied at slide (layout) level or at part level.

Palets

The current version of SLidium only supports one color palet by theme. In order to support in the future multiple palets, they are specified in an array in the JSON file.

A palet has:

  • A name
  • A CSS file
  • A set of colors (in CSS hex format)
    • dark1
    • light1
    • dark2
    • light2
    • accent1
    • accent2
    • accent3
    • accent4
    • accent5
    • accent6
    • accent7

Layouts

  • Each theme can have a set of different layouts.
  • The default layout if the first one in the collection.
"Layouts":[
{
"Name" : "Default",
"Group" :"Basic",
"Snippet": "# Fidele",
"Classes": "titleandcolumns",
"Dynamic": false,
"DynamicPart" :"",
"FixedParts": 1,
"Template": "<div class=\"grid\"><div class=\"column\"> {@{content}@}</div></div>",
"ThumbnailTemplate": "<div class=\"grid\"><div class=\"column\"> <h1>Title</h1>Content of the slide</div></div>"
}
]
view raw layout.json hosted with ❤ by GitHub

Layout template

  • Each layout has a template. It will be used to wrap the converted markdown and will then create a full slide.

Template thumbnail

In addition to the layout template, you can specify an optional property ThumbnailTemplate. It is used to generate a thumbnail of each layout of the theme. You need to specify HTML which will be as the slide content.

Layout parts

Each layout can have different parts. Parts are a way to group slide information in blocks. For instance, a layout having One full-width header and 2 columns below will have 3 different parts. {{CONTENT}}

In the markdown, °°° on a new line indicates to Slidium to move to the next part of the slide.

Fixed layouts and dynamic layouts

  • A fixed layout has a defined number of parts. A dynamic one adapts to its content.
  • An example of fixed layout: A title slide only containing a text.
  • An example of dynamic layout: a slide having one header and a variable number of columns.

CSS

  • It is recommended to use a CSS preprocessor like less or saas to facilitate the CSS generation.
  • Classes
    • Ability to set multiple class to factorize CSS code

Template variables

Slidum provides several variables that can be used either in the slide layout to directly in the presentation.

  • {{SLIDE_NUMBER}} will be replaced by the current slide number.
  • {{SLIDE_COUNT}} will be replaced by the total number of slides in the presentation.

You can combine variables like : Slide {{SLIDE_NUMBER}} of {{SLIDE_COUNT}}

How to test & install themes

  • Open the Slidium user themes directory. In a regular installation, this folder is located here: ~Library/Containers/com.neomobili.Slidium/Data/Library/Application Support
  • You can also reveal this folder in the Finder by going to preferences of Slidum and clicking on the Open Theme Folder button in the Resources tab.
  • Create a new directory for each theme with the name of your theme.
  • Copy to this folder, the theme.json, the theme thumbnail, the CSS and the eventual other assets
  • Modify the theme.JSON file according to your theme
  • Restart Slidum if it is already started or open it otherwise.
  • Create a new presentation using this theme

Other best practices

Images optimization

It is highly recommended to optimize images. You can use the following tools for that purpose:

Documentation and example

  • Slidium allows creating complex slides using markdown. Because layouts are theme specific, it is important to document how to use them.
  • For each layout, the ideal is to provide the markdown code and a screenshot of the result
  • Such example can be found here