Skip to content
markdown note management
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


markdown note management helper


note: nom is written for python 3.

install with either:

pip install nom

or from source:

git clone
cd nom
pip install --editable .

If you wish to use nom clip (to convert clipboard HTML into markdown notes) on OSX, you also need the following:

pip install pyobjc

On Linux, you need pygobject. You can check that it's installed by starting a python interpreter and running:

from gi.repository import Gdk, Gtk


nom --help

Usage: nom [OPTIONS] COMMAND [ARGS]...

  --help  Show this message and exit.

  clip    convert html in the clipboard to markdown
  export  export a note to html
  preach  export a note to an html presentation
  view    view a note in the browse

A bit more about each command:

  • clip: copy some text from a webpage, then run nom clip -s ~/notes/ This will save the html as markdown to ~/notes/ and also download any images to ~/notes/assets/foo/.
    • if you don't pass -s, the markdown is output to stdout
    • pass -e to open the resulting markdown file in EDITOR. only available if -s is specified
    • pass -v to compile and then view the note in your browser
    • pass -o to overwrite an existing note, if there is one
  • view: compiles and opens a note in the browser
    • pass -w to continually watch the original markdown file and its assets and recompile on changes
  • browse: compiles notes in a directory and its subdirectories and opens in the browser
  • export: to export a markdown file with its assets as a self-contained site, run nom export ~/notes/ .. This will create a folder foo with the compiled note and its assets.
    • pass -w to continually watch the original markdown file and its assets and recompile on changes
    • pass -v to view the compiled note in your browser
    • pass -s with a path to a stylesheet to apply style overrides
  • preach: similar to export, except it creates an HTML slideshow, interpreting --- as slide breaks. Slides are advanced using the arrow keys. Accepts the same options as export.

markdown extensions

nom supports the following extra markdown patterns:

  • embed a pdf: ![](/path/to.pdf)
  • embed an mp4: ![](/path/to.mp4)
    • to autoplay an mp4: ![](/path/to.mp4){: autoplay}
  • embed an iframe: @[](


For the preach there is some additional functionality.

First of all, when running a preach presentation it's recommended to use the Python HTTP server:

python3 -m http.server 8001

You can visit localhost:8001 in two separate browser tabs and the presentations will be synced. So you can run a copy on one screen and another on the projector.

Included classes/attributes

There are also some built-in CSS classes for convenience:

  • fullscreen iframe: @[]({: .fullscreen}
  • fullscreen background image: ![](/path/to.jpg){: .background}

Presenter mode

Presenter mode can be enabled with a presenter query param, e.g. localhost:8001?presenter. This mode does the following:

  • Shows slide progress
  • Shows a timer
  • Shows speaker notes (see below)
  • Synchronizes slides (see below)

Speaker notes

You can also include speaker notes as HTML comments, e.g.:

this is my slide

these are my notes for this slide.


this is another slide

these are my notes for the second slide.

Slide synchronization

Often you will want to have one browser tab with the presenter mode and another with the audience mode. When you advance the presenter mode, the audience mode tab should correspondingly advance too.

With preach there are two ways of synchronizing tabs: - Local storage (default), for browser tabs open on the same device (i.e. computer connected to the projector via a direct connection, e.g. HDMI) - p2p via WebRTC, for browser tabs open on separate devices (i.e. laptop with presenter notes, and a separate computer connected to the projector). This requires an internet connection for both devices.

To use the p2p method, you must supply an additional key query parameter to both the presenter and audience mode tabs:

  1. Open the presenter mode tab with a key of your choosing, e.g. localhost:8001?presenter&key=foobar. This tab will be designated the leader for the key foobar.
  2. Open the audience mode tab with the same key, e.g. localhost:8001?key=foobar. This will follow the designated leader for the key foobar.
You can’t perform that action at this time.