Package: ntbk
A simple, opinionated terminal notebook inspired by bullet journaling.ContentsContentsWhy does this exist?Project philosophyInstallationFolder structureUsageOpening today's logOpening logs for other daysListing log filesJotting notesOpening collectionsListing collectionsSubdirectories in collections and logsWriting TemplatesUsing templatesListing available templatesDefault templatesProviding additional template variables in configProviding additional template variables with --vars flagFinding filesFinding directoriesAbbreviated commandsConfigRoadmapContributingWhy does this exist?I used to be a dedicated bullet journaler until I got tired of not always having my notebook and the slowness of writing by hand. I moved my todo list to Todoist and scheduling to a web calendar, however, I still didn't have a good way of handling the long-form writing and journaling I did in my bullet journal. I tried apps like Joplin but I really wanted to only be in the terminal with Vim and nothing else. I tried Vim and NERDTree in Dropbox, which worked, but I felt I needed a way of automating common tasks like opening todays log and collections, so ntbk was born.Project philosophyDon't reinvent the wheel. Todo lists and scheduling are handled better by other apps. Versioning and backup can be done by Dropbox and git. Grep works great for search. These tasks are up to the user and outside the scope of this project. ntbk only provides shortcuts to working with plain text files within its opinionated structure.It should be easy to navigate the generated file tree without ntbk.No databases. Only work with the filesystem.Installationfoo@bar:~$pipinstallntbkOnce installed, just run:foo@bar:~$ntbkYou will be prompted for the notebook directory and editor you want to use. This will create the config file and notebook folders for you then immediately open today's log. By default a simple template for log entries will be created for you at_templates/log_default.md.Folder structureThere are two main entities in ntbk -logsandcollections. Logs are similar to the "daily log" in bullet journaling. They contain text for the current day. Collections on the other hand contain related ideas and topics that don't belong to a particular day. For instance you might have arecipescollection orbookscollection.An ntbk directory will look like the following:ntbk/
    ├─ _templates/
    │  ├─ diary.md
    │  ├─ book-review.md
    ├─ collections/
    │  ├─ reading/
    │  │  ├─ 1984.md
    │  ├─ recipes/
    │  │  ├─ index.md
    ├─ log/
    │  ├─ 2021/
    │  │  ├─ 01-january/
    │  │  │  ├─ 2021-01-01/
    │  │  │  │  ├─ index.md
    │  │  │  │  ├─ work.md
    │  │  │  ├─ 2021-01-02/
    │  │  │  │  ├─ index.mdLog files are organized by year, month, then day. The default file for the day isindex.mdhowever, you can create as many files for the day as you like. This allows you to separate out different things for the day. For instance, you may want to keep your work notes in a separate file, or diary entries in a separate file.Collections are very similar, but are not structured by date. A collection is essentially a folder, and the default file within it isindex.md, though you can create any files within the collection you want.UsageIn the following examples it will be assumed today's date is 2021-12-16.Opening today's logTo open today's log file you can use thetodaycommand.foo@bar:~$ntbktodayThis will open the filelog/2021/12-december/2021-12-16/index.md. The file will be created if it doesn't already exist.Simply running the script without any arguments is the same as using the today command, however, you cannot add any additional arguments like--templateor specify a different file (covered later). It's simply a shortcut to open today's index file.foo@bar:~$ntbkIf you want to open a different file thanindex.mdyou can specify it as another parameter.foo@bar:~$ntbktodayworkWould open/createlog/2021/12-december/2021-12-16/work.mdOpening logs for other daysfoo@bar:~$ntbkyesterdayWould open/createlog/2021/12-december/2021-12-15/index.mdfoo@bar:~$ntbktomorrowworkWould open/createlog/2021/12-december/2021-12-17/work.mdfoo@bar:~$ntbkdate2021-12-01Would open/createlog/2021/12-december/2021-12-01/index.mdNote that in all of these commands theindex.mdfile is implied, unless you specify a different file name.Note - the filenameindex.mdcan be changed with thedefault_filenameconfigvariable.Listing log filesTo list all the files for a given date use the--listflagfoo@bar:~$ntbktoday--listworkindexnotesfoo@bar:~$ntbkdate2021-12-14--listindexJotting notesSometimes you just want to make a quick note without having to open your editor. To do this you can use thejotcommand. This command will only write to today's log.foo@bar:~$ntbkjot"some quick note"Jotted note to today's index fileIf you'd like to jot to a different file you can specify the file after your note.foo@bar:~$ntbkjot"some quick note"notesJotted note to today's notes fileTo automatically add the current time before your jotted note use the--timestampor-sflag.foo@bar:~$ntbkjot"some note"--timestampJotted note to today's index fileOpening collectionsCollections function very similarly to logs. To open/create a collection you use thecollectioncommand:foo@bar:~$ntbkcollectionbooksThis would create the filecollections/books/index.mdIf you want to create a new file inside a collection, just pass it as another argument.foo@bar:~$ntbkcollectionbooks1984Would createcollections/books/1984.mdListing collectionsTo list all your collections:foo@bar:~$ntbkcollectionsbooks [2 files]travel-2022 [1 file]recipes [1 file]To list all the files within a collectionfoo@bar:~$ntbkcollectionbooks--list1984brave-new-worldSubdirectories in collections and logsFor collections, subdirectories are specified as part of the collection name:foo@bar:~$ntbkcollectionbooks/fictionthe-hobbitThis would open/createcollections/books/fiction/the-hobbit.mdListing a subdirectory is the same:foo@bar:~$ntbkcollectionbooks/fiction--listLogs are different since an alias liketodayoryesterdayis often used. So for logs you specify the path with the filename.foo@bar:~$ntbktodaywork/meeting-notesThis would open/createlog/2021/12-december/2021-12-16/work/meeting-notes.mdTo list files for this newworkdirectory, just add a forward slash to the directory name and use the--listflag:foo@bar:~$:ntbktodaywork/--listYou can go as deep as you want with this:foo@bar:~$:ntbktodaywork/meetings/--listIn both collections and logs you can use the--recursiveor-rflag to recursively list all files:foo@bar:~$:ntbkcbooks-lrfoo@bar:~$:ntbktod-lrWriting TemplatesThe third directory in thentbk/folder is_templates. Here you can create markdown files that will be used as a starting point for new files. Templates use theJinja2templating library, so all functions provided by jinja are available.The following variables are available to templates by default. Additional variables can be provided in theconfig fileand also with the--vars flag.VariableTypeExampleNotesnowdatetimeAll python datetime methods are availabletoday_isostring2021-12-16now_isostring2021-12-16T13:18:37today_longstringThursday, December 16, 2021now_longstringThursday, December 16, 2021 01:18 PMlog_datedatetimeOnly available in templates for log files. Represents the date of the file.Given this template:## Built in variables{{ now.strftime('%A') }}
{{ today_iso }}
{{ now_iso }}
{{ today_long }}
{{ now_long }}The following would be rendered:## Built in variablesThursday
2021-12-16
2021-12-16T13:18:37
Thursday, December 16, 2021
Thursday, December 16, 2021 01:18 PMUsing templatesYou can specify a template to be used with the--templateor-targument.foo@bar:~$ntbktodaydiary--templatediaryThis will create thediary.mdfile for today using the_templates/diary.mdtemplate.Collections can also use templates.foo@bar:~$ntbkcollectionrecipesmeatloaf--templaterecipeListing available templatesTo see a list of templates available use thetemplatescommand.foo@bar:~$ntbktemplatesbible-entrygrocery-listbook-reviewjournal_defaultlog_defaultwork-notesDefault templatesYou can also set a default template to be used for log entries and collections in yourconfigfile:default_templates:log:index:log_defaultwork:work_notescollection:books:book_reviewrecipes:recipeThelogsection defines the template to use for each type of log file.For example:foo@bar:~$ntbktodayWould use thelog_default.mdtemplate (note the .md extension is implicit in the config).foo@bar:~$ntbktodayworkWould use thework_notes.mdtemplateFor collections you can only specify a single template to be used by every file in the collection.foo@bar:~$ntbkcollectionbooks1984Would use thebook_review.mdtemplatefoo@bar:~$ntbkcollectionrecipesWould create anindex.mdfile and use therecipe.mdtemplate.If you have a default configured, but also use the--templateargument, the default will be overridden.Note - templates will only be used if the file you're opening doesn't exist or is empty. It will not overwrite existing files with the template contentProviding additional template variables in configIf you have variables you want to be available to every template you can define them in thetemplate_varssetting inyour config. You can provide any kind of data you like here.template_vars:owner:John Doediary_tags:-diary-2021Theowneranddiary_tagsvariables would now be available in your templates.# Diary EntryAuthor: {{ owner }}
Tags: {% for tag in diary_tags %}#{{ tag }} {% endfor %}Providing additional template variables with --vars flagYou can also provide additional variables at runtime with the--varsflag. These variables can only be simple strings in the format ofkey=value. You can provide as many as you like. Any values that contain spaces should be enclosed in quotes.foo@bar:~$ntbkcollectionbooksdune--templatebook_review--varstitle=Duneauthor="Frank Herbert"Finding filesPassing the--findor-fflag will output the files path rather than opening it in your editor.foo@bar:~$ntbktoday--find/home/blake/ntbk/2021/12-december/2021-12-16/index.mdfoo@bar:~$ntbktodaynotes-f/home/blake/ntbk/2021/12-december/2021-12-16/notes.mdfoo@bar:~$ntbkcollectionbooks--find/home/blake/ntbk/collections/booksThis can be useful if you want to do things likecatthe contents of the file:foo@bar:~$cat`ntbktoday--find`Finding directoriesPassing the--find-diror-dflag will output the directory path.foo@bar:~$ntbktoday--find-dir/home/blake/ntbk/2021/12-december/2021-12-16foo@bar:~$ntbkcollectionbooks-d/home/blake/ntbk/collections/booksThis can be useful if you want to do things likecdto the directory:foo@bar:~$cd`ntbktoday-d`Abbreviated commandsThe following command abbreviations are available:today=todtomorrow=tomyesterday=yestdate=dtordcollection=colorccollections=colsThey can be used in place of any normal command. For example, to open the file for date 2021-12-01:foo@bar:~$ntbkd2021-12-01ConfigThe config file is located at~/.config/ntbk/ntbk.ymlBelow is a sample config file with all options documented.# Your notebook folder
ntbk_dir: ~/ntbk

# The editor to be used when opening files
editor: vim 

# Location of templates, relative to ntbk_dir
template_dir: _templates

# Filename to use if one is not specified
default_filename: index

# Mapping of default templates for log and collection files
default_templates:
  log:
    # use the log_default.md template any time an index.md file is created
    index: log_default
    # use the work_notes.md template any time a work.md file is created
    work: work_notes
  collection:
    # use the book_review.md template for all files created in the books collection
    books: book_review
    # use the recipe.md template for all files created in the recipes collection
    recipes: recipe

# User-defined variables that will be available in every template
template_vars:
  # the author var will be in every template and can be used like {{ author.first_name }}
  author:
    first_name: John
    last_name: Doe
  # this list will be available to every template
  default_tags:
    - "2020"RoadmapThere is a lot more that can be done with this app. The following are ideas/features I'd like to pursue:Vim plugin - I'd like to have a plugin so you can run ntbk commands from within vim, rather than going back to the terminalHtml/PDF/etc generation with something like pandoc (or maybe even jekyll)Natural language processing so you can do things likentbk last mondayPossibly an accompanying mobile app one day. I'd like a very basic mobile markdown editor that worked with Dropbox (and maybe others) and had the ntbk shortcuts (today, collections, etc.)ContributingSeeCONTRIBUTING.md