using nb with other markdown notebook editors

[100ideas]

Which markdown notebook apps can integrate easily with nb?

I like nb's command line ui a lot, but sometimes I want to browse and flip through my notes and bookmarks visually. Searching and editing would be nice too.

This issue is for

1. sharing tips and techniques for using other markdown notebooks/editors/viewers with nb notebooks and vice versa; and
2. (extra credit) documenting and discussing how these other tools implement common features in relation to nb, i.e. storing and linking attachments, nesting notes, general data store and format, searching, filenames vs uuids, keeping metadata in multiple notes fresh, etc.

Apps that may work nicely with nb:

• notable - desktop md notebook editor (now closed source since v1.7.3, was agpl)
  • docs(v1.7.3): data directory layout, and linking attachments, notes, tags etc
• boostnote - desktop md notebook editor (gpl3).
  • boostnote data format - "Boostnote saves documents in a folder such as ~/Boostnote as cson files." A single boostnote.json at root contains metadata.
• quiver - MacOs md notebook ($9)
  • Quiver Data Format: subdirectories containing files of.md content, .json metadata, and attachments.
• glow - terminal based markdown reader (MIT) mentioned in #62
• dumper - Library for extracting attachments, notes and metadata out of formats used by popular note-taking apps - evernote, boostnote. (MIT)

[100ideas]

notable

I was able to use notable to open a directory of nb bookmarks/note markdown files. It provides a markdown renderer, editor, and logical tree and tag organizer for the notes.

I just copied the nb markdown files into the notable data directory as a quick test. Going forward I might symlink one or more of my nb notebooks into the data directory notable uses, or just point notable directly at the nb global/local notebook directory. The file name doesn't seem to be important to notable.

notable is a react webapp that runs in an electron container on desktop.

the notable app presents a logical tree of notes based on tags defined in the markdown file's yaml frontmatter. ~~I think nb does something similar, but less structured, by paying special attention to certain md headers for its search and ui tools (## Description and ##Tags).~~ nb just searches for text strings or regexes for the most part. "tags" are just strings that start with hash symbol: #a_tag. nb list does not look anywhere in particular for tag content or other structured content for the most part.

• nb markdown bookmark file format
• nb list src https://github.com/xwmx/nb/blob/5.7.8/nb#L6274
• nb bookmark src: switch statement that EITHER processes page content with pandoc+readable OR saves raw HTML - not both: https://github.com/xwmx/nb/blob/5.7.8/nb#L3752

notable stores all attachments in a separate attachments directory. attachments are linked with special markdown link syntax like [](@attachment/icon_small.png). Currently nb doesn't automatically mirror or make a local copy of images or other files that are embedded in an html page. It also doesn't currently link resources passed in with --related to a bookmark when it is created - see #54.

quick n dirty approaches for tag integration

1. plugin that rewrites how nb formats structured data (tags, notebook links, description) so it is compatible with notable or boostnote etc.

• would be cool if there was an nb api hook that runs during note serialization to which plugins could be assigned as automatic actions
• this plugin would rewrite structured data during note creation as yaml frontmatter, or batch-convert all md files in notebook on user command. could be tricky, since nb only structures data passed in from command-line params (--description, --quote, --tags <tag1>,<tag2>..., --related=<url>) very lightly under md subheaders. so basically would be writing a data extractor for md.
• would nb be able to safely create and use (perhaps not update though) data in yaml frontmatter? don't need yaml parser/validator necessarily if nb only ever creates frontmatter, never updates?
• request/discuss/patch this if going this route. see nb docs creating-plugins and nb src line 3660- shows how nb searches content.

2. patch notable v1.7.3 to scan first ## tags section for all words that start with # - these are the tags from nb - in addition to looking in frontmatter.

• also, prepend tags with '#' if notable creates one (and stores it in frontmatter)

how could nb deal with linked images/attachements created by notable in sibling directory?

not sure nb should be dealing with this - instead, would be better to patch notable just use normal relative paths to reference attached files in a note, as opposed to its current practice of using a special @attachment prefix in markdown img/a tags like this: [](@attachment/<filename>)

references

---

notable docs(v1.7.3) data directory layout:

---
tags: [Basics, Notebooks/Tutorial]
title: 01 - The Data Directory
created: '2018-12-16T21:43:52.886Z'
modified: '2019-06-06T12:20:10.890Z'
---

# 01 - The Data Directory

The data directory is where all your notes and attachments will be stored, it has the following structure:

/path/to/your/data_directory ├─┬ attachments │ ├── foo.ext │ ├── bar.ext │ └── … └─┬ notes ├── foo.md ├── bar.md └── …

## Features

- The data directory gives you freedom since your notes are never locked into some sort of proprietary database, all your files use sane formats and are easily accessible and portable.
- You can open your data directory via `Notable -> Open Data Directory`.
- You can also change data directory at any time via `Notable -> Change Data Directory...`, the current content won't be copied over to the new one.
- You can edit your notes/attachments without even using Notable, all changes you make to them will be reflected here instantly. In fact you could also import a Markdown note simply by copying it into the `notes` directory.

notable docs(v1.7.3) linking attachments, notes, tags etc:

---
attachments: [icon_small.png]
tags: [Intermediate, Notebooks/Tutorial]
title: '10 - Linking Attachments, Notes, Tags and Searches'
created: '2018-12-27T18:53:01.510Z'
modified: '2019-06-06T12:20:11.040Z'
---

# 10 - Linking Attachments, Notes, Tags and Searches

Sometimes, like when writing a tutorial for a note-taking app :wink:, you may need to link to other notes or embed a few attachments. Notable makes this easy for you.

These special links can also be right-clicked so that you can perform some actions on them.

## Attachments

Attachments can be rendered inline, linked to, and linked to via a button. The `@attachment` token is used for this.

##### Syntax

```markdown
![Icon](@attachment/icon_small.png)
[Icon](@attachment/icon_small.png)
[](@attachment/icon_small.png)

Result

Icon

Notes

Notes can be linked to, and linked to via a button. The @note token is used for this. Wiki-style links are supported too.

Syntax

[Shortcuts](@note/07 - Shortcuts.md)
[](@note/07 - Shortcuts.md)
[[Importing|08 - Importing.md]]
[[08 - Importing]]

Result

[Shortcuts](@note/07 - Shortcuts.md)

[](@note/07 - Shortcuts.md)

[[Importing|08 - Importing.md]]

[[08 - Importing]]

Tags

Tags can be linked to, and linked to via a button. The @tag token is used for this.

Syntax

[Basics](@tag/Basics)
[](@tag/Basics)

Result

Basics

Searches

Searches can be linked to, and linked to via a button. The @search token is used for this.

Syntax

[linking](@search/linking)
[](@search/linking)

Result

linking

[100ideas]

Boostnote

boostnote is a popular foss notebook built with react/redux that runs locally in an electron app. It serializes each note to a single cson file containing content as markdown and a handful of other fields for structured data, with a uuid-based filename. attachments are stored in a sibling directory to notes, inside a sub-folder named with the corresponding notes UUID.

"BoostNote.next" is under development (GPL3) https://github.com/BoostIO/BoostNote.next - will look into it in future comment.

Boostnote "classic" is a bit bloated at runtime due to its electron container the ad-hoc architecture of the source code (notable looks cleaner). That said, the project is quite active and there are plenty of examples of contributes modding the source code or adapting it via plugins or external scripts in the projects issue tracker.

Long ago there was a discussion on boostnote issue tracker about how to add a "web clipper" like feature to the notebook - given a url, download page, convert it to html, store in notebook or as a subsection of a note: https://github.com/BoostIO/Boostnote/issues/923. I think nb is doing a good job at this, and could be even better if it could also scrape the "key" media resources on a page, mirror them locally, and rewrite the relevant tags in the source.

• https://github.com/BoostIO/Boostnote/issues/923
• https://github.com/BoostIO/Boostnote/pull/1981
• https://github.com/BoostIO/Boostnote/issues/1356

integration ideas

Skip boostnote classic and look into boostnote.next. run it locally and research its data model. see lib/db/store.spec.ts. create new comment below.

---

References

here is what a boostnote v0.16.1 notebook directory and entry cson file looks like on disk:

# after setting boostnote to use new storage at following directory, and adding 1 note w/ dropped image: 
torchy:~/D/0/boostnote_dev
$ tree
.
├── attachments
│   └── faf0589a-19fb-4b8e-8122-c265c966d2b3
│       └── b5e29722.png
├── boostnote.json
└── notes
    └── faf0589a-19fb-4b8e-8122-c265c966d2b3.cson

3 directories, 3 files

torchy:~/D/0/boostnote_dev
$ cat boostnote.json
{
  "folders": [
    {
      "key": "4cf970603b784778c788",
      "color": "#E10051",
      "name": "boostnote imports"
    }
  ],
  "version": "1.0"
}

torchy:~/D/0/boostnote_dev
$ cat notes/faf0589a-19fb-4b8e-8122-c265c966d2b3.cson
createdAt: "2020-11-11T15:19:44.978Z"
updatedAt: "2020-11-11T15:20:22.643Z"
type: "MARKDOWN_NOTE"
folder: "4cf970603b784778c788"
title: "markdown notebook data formats"
content: '''
  # markdown notebook data formats

  tag added second

  dragged-n-dropped this image into boostnote editor:

  ![Screen Shot 2020-11-11 at 4.05.27 AM.png](:storage/faf0589a-19fb-4b8e-8122-c265c966d2b3/b5e29722.png)
'''
linesHighlighted: []
tags: [
  "markdown"
  "notebook"
]
isStarred: false
isTrashed: false

[xwmx]

@100ideas Thanks for putting all of this together. I've been reading and exploring the links throughout the day and have a lot of thoughts.

[100ideas]

I don't think there's a "right" way to structure things when it comes to filesystem-based organizational patterns - every approach ends up with unavoidable clunkyness one way or another. This makes it hard to feel satisfied when contemplating any solution.

I've been working on a browser-based notebook app which uses a distributed append-only log as its datastore (hypercore/hyperspace/hyperdrive) and syncronization layer. Hyperdrive, which is similar to git in that it can track and clone a directory, includes filesystem structure and metadata (stat) inside its archive and effectively projects the contents of the append-only log into a real directory and its contents on disk. In my use case, the webapp uses the hyperdrive log like an in-memory database (that happens to have some filesystem metadata in it along with content) while on disk the hyperdrive daemon projects the log into modifications of real files stored in a particular directory.

I've been thinking that since the log exists separate from the filesystem on disk, maybe I should make the directory structure used to organize content somthing that is user-configurable based on several common use cases and aesthetics. Should each note be organized into its own folder, named by date, along with all its attachments? Should each be stored as sibling files all in one folder? should each note just be a string stored in a big json file? I could add some logic to the webapp to reconfigure the virtual filesystem structure based on which configuration is desired, and the hyperdrive daemon managing the archive on disk would dynamically rewrite the folder to match. edit: actually, hyperdrive uses the file path as a key, so implementing this with hyperdrive would require more work than I thought.

In the case of nb... one way you could think about something similar would be to write some scripts that bidirectionally transform the notebook directory structure from one style into another and vice-versa, switching to a different git branch in the process. If problems were detected, git switches back to the other branch.

Just food for thought.

[ebridges]

I'm just starting to look into using nb, and really like the straightforward organization of notes. Another .md editor that I'm looking into combining with it is Notebooks

It works from a tree of .md files on the filesystem, and supports links to attachments via a relative link to a subdirectory of the .md file.

[khimaros]

i wanted to share that https://github.com/foambubble/foam also works well with nb notebooks.

[doctorfree]

I am using nb with Obsidian and have found they compliment each other well.