kt3k / remarker

:arrow_forward: Remark cli

remarker v1.15.0

Remark cli

remark is a simple, in-browser, markdown-driven slideshow tool. remarker is a command line tool for building a remark-based slideshow page very easily.

Usage

Install via npm:

$ npm install --save remarker

Write your slide in markdown:

# My Slide

---

# My Slide 2

???

Presenter notes here

---

save the above as slides.md

Invoke remarker command.

$ ./node_modules/.bin/remarker

Or if you have npx command, then hit:

$ npx remarker

This starts a local server at port 6275 (this is configurable) and you can see your slides at http://localhost:6275/.

See remark's slide and documentation for more details about its syntax, features etc.

Build slides

You can build your slides as static page as remarker build command.

$ ./node_modules/.bin/remarker build

This builds your slides as html page under build/ directory. The output directory is configurable. See the below for details.

Installing globally

You can instead install it globally, in one of these two ways:

sudo npm i -g remarker    # from the npm repository
sudo npm i -g .           # if there's a clone in the current directory

After that, you should be able to invoke it this way from any directory in your system:

remarker [build]

Configuration

You can configure remarker with the configuration file remarker.yml:

(Note: remarker.yml should be put in the current directory.)

Default settings are as follows:

port: 6275
dest: build
out: index.html
source: slides.md
title: ''
assets: ['assets']
css: ''
cssFiles: []
script: ''
scriptFiles: []
remarkConfig: {}
remarkPath: moduleDir + '/vendor/remark.js'
scriptFilesAfterCreate: []
livereload: true
livereloadPort: 35729

Basic options

• port is the port number of remarker server. Default is 6275.
• dest is the destination of remarker build command. Default is build
• out is the filename of the result html page. Default is index.html
• source is the source markdown filename. Default is slides.md.
• title is the page title of the slides. Default is an empty string.
• css is css text you want to add to slides' html page.
• cssFiles is the list of additional stylesheet files (URL or the file path relative to your current working director) you want to add to slides' html page. If you provide file paths, these files are copied/served statically. Default is an empty array.

Advanced options

• assets is the list of assets directory. These directories are copied/served statically.
• scriptFiles is the list of additional JavaScript files (URL or the file path relative to your current working director) appended after the remark.js. If you provide file paths, these files are copied/served statically. Default is an empty array.
• script is additional JavaScript code appended after the remark.js and scriptFiles. Default is an empty string.
• remarkConfig is the config object which is passed to remark.create(options). Default is an empty object.
  • See the remark source code for what option is available.
• remarkPath is the path to remark.js. This replaces the original remark.js with specified one.
• scriptFilesAfterCreate is the list of additional JavaScript files (URL or the file path relative to your current working director) appended after the remark.create(). If you provide file paths, these files are copied/served statically. Default is an empty array.
• livereload is the flag to toggle livereloading feature. Default is true.
• livereloadPort is the port number for livereloading websocket connection. Default is 35729.

CLI Usage

Usage:
  remarker [options] serve      Serves all the assets at localhost
  remarker [options] build      Builds all the assets to the dest

Options:
  -h, --help                    Shows the help message and exits
  -v, --version                 Shows the version number and exits
  -s, --source <path>           Specifies the slide's markdown file.
                                This overrides 'source' property of the config file.
  -o, --out <filename>          The output filename of the slides. Default is index.html.
  -d, --dest <path>             The destination directory for built slides.
  -p, --port <number>           The port number for dev server.
  -b, --open-browser            Open the browser to the page when server starts. Default is false.

Examples

• simple example
• remark slides
  • The original remark slides in remarker configuration.
• LaTeX and Mathjax
  • Usage of LaTeX and Mathjax in remarker. Contributed by @michaelliebling.

Motivation of remarker

remark is a great presentation tool and you can write your slide's contents in markdown. The problem is when you simply use remark, you need to maintain the html, css and scripts as well as markdown. If you care the details of design and style of the slides, that's fine. However if you don't care the design of the slides that much and want to focus only on the contents, then the settings of css, html, scripts seem quite messy. remarker solves this problem. remarker separates the contents (= markdown) from the settings (css, html, scripts). So you can only focus on and keep maintaining the contents of the slides and let remarker do the rest of the work. This is easier than using remark directly.

How-tos

How to use images in slides

Put the images under ./assets directory and they are automatically served/copied and you can reference it like <img src="assets/my-diagram.png" width="600" /> in your slides.

The directory name of assets can be configured in remarker.yml. See the configuration section for details.

Who uses this tool?

See this search.

History

• 2022-11-24 v1.15.0 Added loading indicator.
• 2022-02-13 v1.14.0 Fixed error while changing slides.md
• 2020-05-11 v1.12.0 Added scriptFilesAfterCreate option.
• 2019-10-18 v1.11.1 Fix dependency.
• 2019-10-18 v1.11.0 Added -b, --open-browser option.
• 2019-05-14 v1.10.0 Added --dest, --out, and --port CLI options.
• 2018-08-06 v1.9.0 Added :emoji: transformation. Modify cssFiles option handling (#11).
• 2018-06-10 v1.8.1 Fixed help and version options.
• 2018-06-10 v1.8.0 Added livereloading feature.
• 2018-01-29 v1.7.0 Enabled file asset (#8).
• 2018-01-13 v1.6.1 Fixed -s option.
• 2018-01-12 v1.6.0 Added --source cli option.
• 2017-08-05 v1.3.0 Added remarkConfig prop.

License

MIT

remarker's Issues

Customization of remark.js

Can we configure so that we can use another version of remark.js? Currently, I think it is hard-coded and bundled together (vendor/remark.js). It would be great to allow customization of scripts, not only specifying the version or path to remark.js, but also injecting custom javascript code (like css).

One another problem is that is not a minified version; viewing source is quite annoying. Moreover, I think it'd better to load remark.js as an external resource (e.g. script src) by default.

Request: Support for passing remark configuration

Hi, it would be nice to have a way to write the remark configuration right in the YML, is this something being considered?
Thanks

Specify dest, port, etc from CLI opts

• --dest destination dir
• --port port number
• -o, --out output html name. Default index.html

This not a critical issue, but make user confuse.

(node:512) MaxListenersExceededWarning: Possible EventEmitter memory leak detected. 11 unpipe listeners added to [DestroyableTransform]. Use emitter.setMaxListeners() to increase limit
(node:512) MaxListenersExceededWarning: Possible EventEmitter memory leak detected. 11 drain listeners added to [DestroyableTransform]. Use emitter.setMaxListeners() to increase limit
(node:512) MaxListenersExceededWarning: Possible EventEmitter memory leak detected. 11 error listeners added to [DestroyableTransform]. Use emitter.setMaxListeners() to increase limit
(node:512) MaxListenersExceededWarning: Possible EventEmitter memory leak detected. 11 close listeners added to [DestroyableTransform]. Use emitter.setMaxListeners() to increase limit
(node:512) MaxListenersExceededWarning: Possible EventEmitter memory leak detected. 11 finish listeners added to [DestroyableTransform]. Use emitter.setMaxListeners() to increase limit

Livereload: After two reload, livereload stop to working....

Hello,

when I'm working on a presentation with livereload. After two modifications, livereload doesn't take care of my extras modifications.

Do I miss something in my configuration file?
Or on my workstation (ubuntu: 18.04)??

Thanks for your help

no way to supply single files as assets

I'd like to supply a single file as asset, such as a favicion.ico, however, the asset array assumes all elements are directories.

Is there any way to fix that?
because even if i "manually" copy the file in a script line:

{
  "dependencies": {
    "remarker": "^1.6.2"
  },
  "scripts": {
    "build": "remarker build; cp favicon.ico build/",
    "serve": "remarker serve",
    "clean": "rm -rf build"
  }
}

it won't work, because the assets array is also used to build what's being served.

Program line argument to specify the source

It would be great to have a program line argument to pass the slide markdown file to the remarker:

npx remarker --source myslide.md

Because I have multiple slides at the moment in the same folder and would like to leave the name as it is.

Feature Request: Specify the remark.js folder.

Please add YAML entry to specify a folder for remark.js

add livereload

• vinyl-serve deps update
• vinyl-serve refactoring
• vinyl-serve use connect
• vinyl-serve accept middleware
• bulbo accpet middleware
• berber accept middleware
• set connect-livereload in remarker
• set gulp-livereload in remarker
• add test of livereload

Feature request: live reload for development

It's a bit of a pain to keep having to Cmd-R in the browser whenever a file has been changed. Is there any way to enable LiveReload so that the browser refreshes when the slide content is saved?

1.9.1 version is broken?

npx --registry=https://registry.npmjs.org/ remarker -s webpagetest-meetup-slides.md

ENOENT: no such file or directory, open '/Users/kobi.kadosh/.npm/_npx/67802/lib/node_modules/remarker/assets/default.css'
Error: Name is not specified. you have to name your command by berber.name(name).
    at Berber.checkName (/Users/kobi.kadosh/.npm/_npx/67802/lib/node_modules/remarker/node_modules/berber/src/berber.js:20:13)
    at Promise.resolve.then (/Users/kobi.kadosh/.npm/_npx/67802/lib/node_modules/remarker/node_modules/berber/index.js:8:29)

where to put the remarker.yml to?

the README.md does not tell the location to put remarker.yml

where to put it ? which location

Feature Request: Multiple presentations

It'd be nice if one were able to serve/build multiple .md from one source directory. Each presentation would then be built as a separate HTML file.