markpress
v4.0.0
Published
A tool to generate impress.js presentations from markdown files
Downloads
16
Readme
Markpress
markpress
is a command line tool and node package to convert markdown files into self-contained impressjs html
presentations. It was initially inspired and based on markdown-impress by steel1990.
This is the outcome of feeding this very README.md
to markpress: $ markpress README.md
How to install
You'll need node
version >= 5.0.0
installed on your system.
$ npm install -g markpress
(globally)
or
$ npm install markpress
(for the current folder only)
Features
- Automatic slide layout generation
- Automatic slide split by
h1
- Built-in themes (
dark
,light
,dark-serif
,light-serif
). Customizable through<style>
tags. - Generates self-contained HTML file by embedding images (no network connection needed when presenting)
- Code highlighting for most common programming languages
- Supports HTML & Emojis! :smile::thumbsup: :camel::dash:
- Live editor mode via the
--edit
option to live-preview your changes - Responsive design adapts to different screen sizes
- Adaptive text size (using
vmin
andvmax
) - Github-inspired CSS styles
- Will run fine in the latest Firefox, Chrome, Safari and probably Edge *
Usage
CLI
$ markpress <input file> [output file] [options]
If no output
file is passed, the input
's filename will be used with .html
extension.
More information: $ markpress -h
In your code
See Examples section for more.
const fs = require('fs');
const markpress = require('markpress');
const options = { ... };
markpress('input.md', options).then(({html, md}) => {
fs.writeFileSync('output.html', html);
});
// or you can pass the Markdown content directly as parameter
markpress('# Markdown content \n > Blockquote', options).then(({html, md}) => {
fs.writeFileSync('output.html', html);
});
Markdown format, Custom Layout and Styles
- Github Flavored Markdown format is supported via marky-markdown package, including tables.
- Use
------
to separate each slide, or user the-a
option to generate a slide each time anh1
element is found. - Use HTML comments to set impress slide attributes, such as
<!--slide-attr x=0 y=0 rotate=0 scale=1 -->
. Example - You can customize the styles by embedding CSS in
<style>
tags as you would in any HTML - be careful as an empty slide will be created when including styles at the top and enabling the-a --auto-split
flag. - You can embedded any HTML in your markdown file and it will be included in your slides HTML.
Options
The options precedence is as follows (higher in the least means higher precedence):
- Options passed directly through
CLI
/ code. - Options embedded in the
.md
file (see--save
option)
-a
, --auto-split
or { autoSplit: Boolean }
in code
Default: false
Automatically create a slide for every H1
(# Heading 1
) level element (if ------
are present will be removed and ignored)
-l
, --layout
or { layout: String }
in code
Default: horizontal
Automatically generate the layout for the slides. This option will be ignored if any HTML comment specifying slide positioning attributes is found, so please remove all slide-positioning comments (<!--slide-attr ... -->
) from the markdown file if you want to use this feature. Available Layouts:
horizontal
(default): Slides positioned along thex
axis. Examplevertical
: Slides positioned along they
axis. Example3d-push
: Slides positioned along thez
axis. Sliden
will be positioned lower thann+1
. Example3d-pull
: Slides positioned along thez
axis. Sliden
will be positioned higher thann+1
.grid
: Slides positioned along thex
andy
axis in a grid fashion. Examplerandom
: Slides positioned randomly on a 5D space (x
,y
,z
,rotate
,scale
). Note that this layout generator might position slides on top of each other. Re-generate until a satisfactory layout is generated. Examplerandom-7d
: [warning: messy] Slides positioned randomly on the 7D space (x
,y
,z
,rotate-x
,rotate-y
,rotate-z
,scale
). This layout generator might position slides on top of each other. Re-generate until a satisfactory layout is generated. Example
-E
, --no-embed
or { embed: false }
in code
Default: true
(pass --no-embed
through CLI to disable)
By default, markpress
will try to embed (using base64 encoding) the referenced images into the HTML so they will be available offline and you will not have problems moving the HTML to other folders. This feature will be disabled if --no-embed
is set to true.
-z
, --sanitize
or { sanitize: boolean }
in code
Default: false
(dangerous HTML & scripts allowed)
Disallow embedding of dangerous HTML code in the Markdown file. You should leave it disabled if you want to use custom <style>
tags, embed videos, etc.
--silent
or { verbose: Boolean }
in code
--silent
Will silence all console output in the Terminal. {verbose: true}
will enable all console output.
Default (CLI): silence
: false
(all console output enabled by default)
Default (module): verbose
: false
(all console output disabled by default)
-t <theme>
, --theme <theme>
or { theme: String }
in code
Default: light
Chose from the different available themes:
light
(default): Light theme with Sans-serif fontdark
: Dark theme with Sans-serif font. Examplelight-serif
: Light theme with Sans-Serif font. Exampledark-serif
: Light theme with Serif font
-s
, --save
or { save: Boolean }
in code
Default: false
Embed the markpress options into the .md
file for portability. Warning: it will override any existing options.
-e
, --edit
only available in CLI
Start edit mode. This will start an embedded web server to preview the resulting HTML with live refresh upon input file change. Press ctrl+c
to stop the server.
Developing
Run
$ node --harmony ./bin/markpress.js input.md
Debug
$ node debug --harmony ./bin/markpress.js input.md
Linking
npm link
Installing local version globally
npm install . -g
API
markpress(input, options)
input
An String
with either:
- The path relative to the execution directory to the input Markdown file. e.g.
../input.md
,/abs/path/input.md
- A Markdown-formatted
String
options
An Object
containing the options as specified in the Options section
returns
A Promise
which will call it's resolve
method with an Object
with two properties:
html
: The htmlString
produced from the Markdown input.md
: [Optional] - If this parameter is defined, it contains the Markdown input updated with the embedded options (see--save
option).
Note that you can use ES6 destructuring to simulate Python's named parameters in JS.
Examples
const fs = require('fs');
const markpress = require('markpress');
const options = {
layout: 'horizontal',
theme: 'light',
autoSplit: true,
allowHtml: false,
verbose: false,
title: 'Optional <title> for output HTML'
}
// Simulating named parameters through destructuring
markpress('input.md', options).then(({html, md}) => {
fs.writeFileSync('output.html', html);
// if `md` is defined it contains the markdown content with embedded options (see --save option)
});
// or you can pass the Markdown content directly as parameter
markpress(
'# This is markdown content \n > Test Blockquote',
options
).then(({html, md}) => {
fs.writeFileSync('output.html', html);
});
Roadmap
Roadmap of planned features can be found here. Suggestions are welcome.
Contributing
Please see CONTRIBUTING.md
References and tools used
- Inspired by and based on:
- https://github.com/steel1990/markdown-impress
- https://www.npmjs.com/package/impress.md
- Styles based on:
- Github markdown CSS: https://github.com/sindresorhus/github-markdown-css
- Atom Code highlighting CSS:
- Dark: https://github.com/atom/atom-dark-syntax
- Light: https://github.com/atom/atom-light-syntax