[ANN] NoteMate.jl: The Perfect Companion for Working with Your Notes

Package Announcements
, ,
1

Hi all, :wave:

I recently just released a new package called NoteMate.jl with the tagline

The perfect companion for working with your notes :books:

It grew out of a personal collection of scripts I had been developing for over year to parse my personal knowledge base, analyze my own thinking, and deploy pages quickly to my personal website.

What Problem Does NoteMate Solve? :thinking:

Here’s the problem it solves for me; if this sounds like you or you are in a similar situation, you may be interested in this package:

All my notes in my knowledge base are written in Common Mark markdown syntax (with a pandoc citation extensions). This is great for portability and I can view it on any editor, browser, or device. However, sharing these notes can be a challenge. Do I run pandoc on selected notes and create a PDF that I send to people? What if I have multiple files to share over and over again? I found this process growing very tedious for myself personally until I decided, “hey, what if I just publish all my notes on my website for easy, winsome, and rapid access? Like an online digital garden?”

I explored this option for a while and really liked the idea from other people’s websites. There was only one problem: nearly all Static Site Generators (SSGs) have their own mark-up! I don’t want to marry my knowledge base to one SSG and rewrite all my notes to match that markup! :scream:

And that’s where NoteMate comes in!

What Does NoteMate Do? :face_with_raised_eyebrow:

Using NoteMate, you are able to do the following sort of workflow:

  1. Parse a NoteMate supported filetype
  2. Convert the parsed note into a “Note” object (Julia representation of your note)
  3. Generate custom citation renders and creation via the pandoc JLL and the bibtex and CSL standards
  4. Target a Note object to the desired mark-up syntax for an SSG
  5. Put your newly converted notes into your SSG

And this whole workflow works without ever modifying your original notes. In this way, you can maintain maximum productivity without care to whatever SSG you might want to deploy to in the future.

How Does It Work? :alembic:

NoteMate is a bit of a strange package as its purpose isn’t to create notes but to interact and work with them. As a result, this package is really an implementation of one of my core ideas in note taking: The Open Knowledge Model (OKM). The OKM is not an implementation but rather a standard that any format you choose to take your notes in can follow. I have prioritized Markdown first as that is the implementation I use, but one can implement the OKM in any file type (txt, md, asciidoc, org, norg, etc.).

:construction: If you want to adapt your notes for use with NoteMate.jl, you must format your notes following the OKM standard! :construction:

Here’s an example outline and implementation of how I write my notes in the OKM: My Note Templates

How Do I Get Started? :memo:

Here is a beginner tutorial showing how NoteMate.jl can be used with Markdown to generate your own workflow process: Markdown Tutorial · NoteMate.jl

In the future, I want to make a video tutorial for this, but here is the script I use to generate my own website with NoteMate: https://github.com/TheCedarPrince/thecedarprince.github.io/blob/main/scripts/note_generator.jl Feel free to adapt that as you desire!

What Are NoteMate’s Current Features :sparkles:

Here are some of the major features for NoteMate as of v0.0.1 release:

  1. Parse notes following the OKM to a NoteMate “Note” object
  2. Generate inline citations and bibliographies via CSL files
  3. Tutorials and documentation
  4. SSG target output support for:
  5. Parser input support for:
    • Common Mark Markdown
    • Pandoc Markdown
  6. Initial test coverage

Final Thoughts :stars:

I know, v0.0.1 is a bit of an odd milestone to release a package at, but I wanted to release early for a few reasons:

  1. People are already starting to copy or use inspirations from NoteMate.jl without the nice tools I have developed.
    • Of note, @indymnv on their website has started using the OKM in the wild already
    • Some of my former student assistants want to make blogs like mine
  2. I fully intend on continuing to maintain this package as I move forward; I use it all the time for my own personal blog: jacobzelko.com/
  3. I wanted to put all the release details in place before starting graduate school to make adding features, bugfixes, etc very straightforward as I am not sure as to how much time I shall have in the future.

In terms of future features I want to add, here are some thoughts:

  • Composition with Buttondown.jl to make newsletters rapidly
  • Complementary analysis tools that can build on top of “Note” objects (like performing graph network analyses, time series visualizations, etc.)
  • Bidirectional parsing from Franklin notes back to NoteMate “Note” objects
  • Functions to coalesce multiple notes into a nicely formatted final, single document
  • Functionality to automatically add bidirectional links between notes
  • Enhanced test suite
  • Video tutorial showing the whole end-to-end pipeline

There are certainly more things to add and do, but now that the initial groundwork is laid, hopefully, things should be more straightforward in building new features, fixes bugs, etc. If you want more parsers for different file types, other functionalities, or what have you, please open an issue and let me know!

~ tcp :deciduous_tree:

P.S. Thanks to @tlienart for revolutionizing how I think about SSGs, Sevoris Doe for encouragement in building the package, and my former student assistants for asking me about the technical details of my website!

19 Likes