npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

markpress

v4.0.0

Published

A tool to generate impress.js presentations from markdown files

Downloads

9

Readme

Markpress

Markpress npm badge Build Status node GitHub stars GitHub followers

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 and vmax)
  • 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 an h1 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 the x axis. Example
  • vertical: Slides positioned along the y axis. Example
  • 3d-push: Slides positioned along the z axis. Slide n will be positioned lower than n+1. Example
  • 3d-pull: Slides positioned along the z axis. Slide n will be positioned higher than n+1.
  • grid: Slides positioned along the x and y axis in a grid fashion. Example
  • random: 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. Example
  • random-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 font
  • dark: Dark theme with Sans-serif font. Example
  • light-serif: Light theme with Sans-Serif font. Example
  • dark-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 html String 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

Thanks for reading until the end :grin: