Need help with cadmus?
Click the β€œchat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

RyanGreenup
138 Stars 6 Forks 278 Commits 11 Opened issues

Description

Shell Scripts to Facilitate Effective Note Taking

Services available

!
?

Need anything else?

Contributors list

# 239,129
ffmpeg
spotify
apple-m...
music-b...
3 commits
# 28,467
xxe
kali-li...
tpu
progres...
1 commit

cadmus

Shell Scripts to Facilitate Effective Note Taking

See the Documentation here

Introduction

This is a self-contained shell script that uses pre-existing tools (such as TMSU and recoll) to provide an interface for markdown notes.

It's command based and prints out available subcommands for any given command, these means you can use a directory of markdown files like a personal wiki, much like OneNote/Evernote/Notable, for example:

Mindmap of Program Flow

and an overview of what it looks like in the terminal

For example if you wanted to extract all the tags from your markdown notes (either

#tags
or from the YAML), cadmus has a tool for that:

Ultimately the idea is it is to act a menu to dispatch different scripts I already had so I could more easily share those scripts with classmates.

The real heavy lifting is done by Pandoc, Recoll, ripgrep, skim/fzf, TMSU etc.

Installation

cadmus is available on the AUR, generally however cadmus will operate in a portable fashion to

~/.cadmus/
, so just using
git
is fine as well:

Automatic

Copy this into your shell:

cd $(mktemp -d)
wget https://raw.githubusercontent.com/RyanGreenup/cadmus/master/install.sh
bash install.sh
  • Cadmus will work from within a self-contained directory and add a symlink to
    ~/.local/bin
    • in this way it's zero lock-in, it does not modify your curr directory of Markdown files.
  • Installation will automatically create a config file in its directory (which is by default
    ~/.cadmus
  • The script will list any dependencies that are not satisfied.

Manual

To install manually:

  1. satisfy the dependencies
  2. Set up Recoll
  3. Download cadmus and put it into the

    PATH
    bash
    git clone https://github.com/RyanGreenup/cadmus ~/.cadmus  \
    || echo "Delete $HOME/.cadmus first"
    mkdir -p $HOME/.local/bin
    ln -s "$HOME/.cadmus/bin/cadmus" "$HOME/.local/bin/"
    
    1. According to the SystemD Standard

      ~/.local/bin
      should be in
      $PATH
      , if you are using some other init implementation you can add this directory to
      "$PATH"
      it by doing something like this:
      ## Should work in bash/zsh/fish
      echo $PATH | grep "$HOME/.local/bin" &> /dev/null && echo "$HOME/.local/bin in path already" || ls "$HOME/.local/bin" &> /dev/null && echo 'PATH="$PATH:$HOME/.local/bin"' >> $HOME/.profile
      
      

When first run, the script will prompt you to make a config file in the directory in which it is run.

Assumptions

It is assumed that:

  1. Notes are:
    1. Markdown files with a
      .md
      extension
    2. Recoll updates it's index on the fly
      • The notes directory will need to be indexed by Recoll in order for the results to show up when using
        cadmus search
        .
  2. SSD
    • I use an SSD and so I let some scripts be pretty inefficient (for example something like
      grep | cut |
      xargs find
      to avoid creating a variable), I don't know if HDD performance would be great.
  3. All Notes have Unique Names
  4. On MacOS you'll need to define
    xdg-open
    and have GNU coreutils, so do something like:
    bash
    alias xdg-open='open &>/dev/null' 
    alias realpath=grealpath &>/dev/null
    

Configuring recoll

Currently the search just uses the default recoll config, I intend to modify this to use

~/.cadmus
as a config directory so as to not interfere with the default config.

It isn't in practice an issue if

~/.recoll
is indexing more than the notes because you can just modify the call to Skim (
sk
) in ..cadmus.. to start the call with
~/Notes/MD
. <!--- By default Cadmus will use a rcoll configuration at
~/.cadmus
, this is to ensure that it doesn't conflict with any previous configuration.

Set this up by performing:

mkdir ~/.cadmus
recoll -c ~/.cadmus

then select index configuration and configure recoll to have

~/Notes/MD
as the top directory and to exclude
~
, ideally
recoll
will index live which can configured with indexing schedule. Recoll will then start indexing the files and afterwards (β‰… 1-2 minutes) the GUI will pop up and you can confirm that the indexing was successful.

|:note: NOTE| | --- | | If you want to change the notes directory change the variable

NOTES_DIR
in *cadmus* |

-->

Design Philosophy

  • *cadmus* acts as a menu for scripts to achieve things
    • The Actual work will be done by subscripts denoted by
      description.bash
      • The subscripts will take the note directory as an argument so they are portable and modular
    • The Arguments will be shifted and then all passed down to subfunctions
    • the script name ~~will~~ should always be printed to the terminal so the individual script can be repurposed with out fishing through code.
  • Subscripts ~~will~~ should take only one argument (or
    STDIN
    )
    • If the first argument is either
      -h
      or
      --help
      help will be printed and then
      exit 0
    • This might lead to some limitations but the simplicity is for sanity, modularity and extensibility.
    • Will always return absolute path.
      • I played around with relative path but it got confusing when calling the script from inside a function inside a script, so instead if you want a relative path you should do
        scriptname './' | xargs realpath --relative-to='./'
  • Be a Front end to tie together different scripts and tools
  • Don't replicate work other people have done.
  • Plain Text, Free as in Speech and Beer.
  • try to make modular subscripts:
    • Pipe in input, output goes to STDOUT
    • Leave Aliases and piping to the user

Dependencies

Recommended for all Features

Interesting / Helpful / Recommended Generally (Not strictly necessary)

PATH

If any dependencies are installed with

pip
or
cargo
it will be necessary to add these directories to your
PATH
:
## bash
echo '
export PATH="$HOME/.local/bin:$PATH"
export PATH="$HOME/.cargo/bin:$PATH"
' >> ~/.bashrc

zsh

echo ' export PATH="$HOME/.local/bin:$PATH" export PATH="$HOME/.cargo/bin:$PATH" ' >> ~/.bashrc

fish

echo ' set PATH $HOME/.local/bin $PATH set PATH $HOME/bin $PATH set PATH "$HOME/.cargo/bin $PATH ' >> ~/.config/fish/config.fish

Recommended Aliases

I wrote all this with aliases in mind, when I settle on some aliases i'll put up my

fish
functions. (I also wanted autocomplete)

Why / Comparison with other tools

So the boxes I needed ticked are, more or less: π„ž | | FOSS | Offline | Linux/BSD? | terminal? | RawFiles? | Markdown | AnyEditor? | |-----------|------|---------|------------|-----------|-----------|----------|------------| | OneNote | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | EverNote | ❌ | ? | ❌ | ❌ | ❌ | ❌ | ❌ | | Notable | ❌ | βœ… | βœ… | ❌ | βœ… | βœ… | βœ… | | Zim | βœ… | βœ… | βœ… | ❌ | βœ… | βœ… | βœ… | | Obsidian | ❌ | βœ… | βœ… | ❌ | βœ… | βœ… | βœ… | | dokuwiki | βœ… | ❌ | βœ… | ❌ | βœ… | βœ…* | βœ… | | joplin | βœ… | βœ… | βœ… | βœ… | ❌ | βœ… | ❌ † | | mediawiki | βœ… | ❌ | βœ… | ❌ | ❌ | ❌ | ❌ ‑ | | Org-Mode | βœ… | βœ… | βœ… | βœ… | βœ… | ❌ | ❌ | | Cadmus | βœ… | βœ… | βœ… | βœ… | βœ… | βœ… | βœ… |

† You can't open the files from vim with FZF so it gets a no.
‑ Unlike dokuwiki everything is in a database so it gets a no
* With a Plugin

Related

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.