9/1/2016: I'm no longer maintaining nomadic
. The tool I use now for managing my Markdown notes is nom
, which is basically nomadic
without the web interface (I didn't use it much).
nomadic
...
- is a simple daemon/web service that makes managing notes nicer.
- supports a simple directory structure of markdown, txt, and pdf notes and any other files which are referenced from them.
- provides an easier way of searching through and browsing those files through either the command line or a simple web interface.
For example, you might have a folder like this:
notes
├── math
│ ├── my math notes.md
│ └── assets
│ └── some image.png
├── programming
│ └── scala guide.md
└── some note.md
I recommend using nomadic
with SyncThing to keep
notes synced across devices. With this setup, nomadic
becomes a decentralized,
simplified alternative to Evernote and other note-taking services.
Since nomadic
runs a small server for browsing files, you can access your notes remotely that way as well.
- Supports GitHub-Flavored markdown
- Supports MathJax syntax
- Supports references to images and other files, and will automatically update those references if the files are moved
- Full-text search (across txt, markdown, and even pdf files)
- A tool for saving copied html as markdown (external images are automatically saved locally)
- Serves a browsable site of all your notes
- Complete command-line interface
- Export notes as portable presentations or as standalone html documents
$ git clone https://github.com/frnsys/nomadic.git
$ cd nomadic
$ pip install .
# install front-end packages
$ cd nomadic/server/assets/
$ bower install
# build the highlight.js library
$ cd static/vendor/highlight.js
$ npm install
# ...with all languages
$ node tools/build.js
# ...or with only specific languages
$ node tools/build.js python ruby javascript scala java bash http sql cs cpp css json objectivec xml markdown apache nginx
# install search dependencies
# ubuntu:
$ sudo apt-get install silversearcher-ag
# osx:
$ brew install the_silver_searcher
If you wish to use nomadic clip
(to convert clipboard HTML into markdown notes) on OSX, you also need the following:
$ pip install pyobjc
If you wish to be able to search through PDFs, you also need the following:
# ubuntu (package manager's version may be out of date, must be >= 1.4):
$ sudo apt-get install libpoppler-cpp-dev
$ git clone https://gitlab.com/pdfgrep/pdfgrep.git /tmp/pdfgrep
$ cd /tmp/pdfgrep
$ bash autogen.sh
$ ./configure
$ make
$ sudo make install
# osx
$ brew install pdfgrep
Create a config file (optional) at ~/.nomadic
in YAML format. See Configuration for more details.
If you don't create this config file, nomadic
will create one for you.
The daemon watches your notes directory and automatically updates the index as they change. It will also automatically update references to other notes as they change.
The daemon also runs a small server which allows for easy browsing/searching through notes as well as a quick way of previewing notes as you work on them.
If you're on a Linux distro that uses Upstart, you can do:
$ sudo cp scripts/nomadic.conf /etc/init/nomadic.conf
Then to start the daemon right away:
$ sudo start nomadic
If you're on OSX, you can do:
$ cp scripts/com.nomadic.plist ~/Library/LaunchAgents/com.nomadic.plist
Then you can start the daemon right away:
$ launchctl load ~/Library/LaunchAgents/com.nomadic.plist
nomadic
checks for a configuration at ~/.nomadic
. If you
start nomadic
without a config, one will be created for you.
For example:
root: ~/notes
Whenever you change this file, you must restart the nomadic
daemon:
# Linux (Upstart)
$ sudo restart nomadic
# OSX (there might be a better way)
$ pkill -f nomadic-d; launchctl start com.nomadic
You can specify a custom stylesheet to override the default one. In your config, specify the path to that stylesheet:
...
override_stylesheet: ~/path/to/my/styles.css
...
Run the nomadic
daemon if it isn't running already.
$ nomadic-d
Primary interaction with nomadic
is through
the command line.
$ nomadic --help
Usage: nomadic [OPTIONS] COMMAND [ARGS]...
Options:
--help Show this message and exit.
Commands:
browse browse notes via the web interface
clean remove unreferenced asset folders
clip convert html in the clipboard to markdown
export export a note to html
new create a new note
search search through notes
You can browse this notes site by running:
$ nomadic browse
which opens up the root directory ('notebook') in your default web browser.
You can immediately jump to a specific notebook by passing its name in:
$ nomadic browse economics
If the specified name matches multiple notebooks, you'll be given the option to select the right one.
You can search through your notes by running:
$ nomadic search <query>
This will present a list of results, along with snippets where the keyword was found, for you to choose from.
nomadic
can search through markdown, txt, and pdf files.
If you are going to be referencing other files in your notes,
you should put them in a directory called assets
in
that note's notebook directory. nomadic
recognizes these
directories and handles them specially.
You can export a note to a standalone html document pretty easily.
For example:
$ nomadic export path/to/some_note.md path/to/export/to
This compiles the note to the specified folder, copying over images.
If you will be making changes to the note, you can specify --watch
to recompile the note when it changes.
Similarly, you can export a note as a standalone html presentation:
$ nomadic export --presentation path/to/some_note.md path/to/export/to
The compiled HTML includes a script which breaks the note into slides according
to <hr>
tags (specified in markdown as ---
, ***
, or ___
). Slides resize to take
up the full window height, and any slides that are too tall are automatically scaled down.
You can use the up/down arrow keys to navigate.
- You can view the 20 most recently modified notes using the
/recent/
path in the web browser.
$ git clone https://github.com/frnsys/nomadic.git
$ cd nomadic
$ pip install --editable .
This installs the package locally, allowing you to work on it and test it easily.
To run the included tests:
$ pip install nose
$ nosetests test