355 lines
14 KiB
Text
355 lines
14 KiB
Text
*mbnotes.txt* Max Bucknell's notes framework
|
|
|
|
==============================================================================
|
|
1. Contents *mbnotes-contents*
|
|
|
|
1. Introduction ...................... |mbnotes|
|
|
2. Setup ............................. |mbnotes-setup|
|
|
2.1. Installation ................ |mbnotes-install|
|
|
2.2. Quarto Project .............. |mbnotes-quarto-project|
|
|
3. Creating Notes .................... |mbnotes-creating|
|
|
3.1. New Notes ................... |mbnotes-new|
|
|
3.2. Daily Notes ................. |mbnotes-daily|
|
|
3.3. Extracting Notes ............ |mbnotes-extracting|
|
|
4. Rendering Notes ................... |mbnotes-rendering|
|
|
5. Configuration ..................... |mbnotes-config|
|
|
6. Integrations ...................... |mbnotes-integrations|
|
|
6.1. UltiSnips ................... |mbnotes-ultisnips|
|
|
6.2. FZF ......................... |mbnotes-fzf|
|
|
|
|
==============================================================================
|
|
1. Introduction *mbnotes*
|
|
|
|
At the start of 2025, I started to use Vim for my digital notes, aiming to
|
|
combine all of the features I liked from the various tools I had used over the
|
|
years. This included:
|
|
|
|
* Markdown
|
|
* Convenient exporting to PDF and HTML
|
|
* Callout blocks of varying colours
|
|
* Linking
|
|
* Tagging
|
|
* Daily notes that I can write in currently, retrospectively, and in advance
|
|
* Interpolation of both mathematical text and code
|
|
* Embedding of code to be executed.
|
|
|
|
Most of this came out of the box with Quarto, at least with some configuration.
|
|
This plugin consists of support for that, along with other conveniences to
|
|
better glue it all together.
|
|
|
|
==============================================================================
|
|
2. Setup *mbnotes-setup*
|
|
|
|
Vim 9 is required for this plugin to work, since it is written in Vim9Script.
|
|
|
|
|
|
2.1. Installation *mbnotes-installation*
|
|
|
|
This plugin can be installed using whatever plugin installer you so desire. It
|
|
also depends on quarto-vim, which itself depends on vim-pandoc-syntax. For
|
|
vim-plug >vim
|
|
|
|
Plug 'vim-pandoc/vim-pandoc-syntax'
|
|
Plug 'quarto-dev/quarto-vim'
|
|
Plug 'maxbucknell/vim-mbnotes'
|
|
|
|
Please note that you must also set |g:mbnotes_dir|
|
|
|
|
g:mbnotes_dir *g:mbnotes_dir*
|
|
|
|
This is the root directory of all notes. It must be set before any
|
|
functionality can be used. If it is not set, the plugin will not start, and
|
|
will echo an error message.
|
|
|
|
Set in vimrc >vim
|
|
|
|
let g:mbnotes_dir = $HOME .. "/notes"
|
|
|
|
This directory and a subdirectory `daily` will be created. The latter is used
|
|
for storing daily notes. See |mbnotes-front-matter| for configuring rendering
|
|
options.
|
|
|
|
2.2. Quarto Project *mbnotes_quarto_project*
|
|
|
|
While MBNotes supports `g:mbnotes_dir` pointing at any directory, it is
|
|
recommended that this be configured to be a Quarto project, of type "default".
|
|
There are a couple of benefits here:
|
|
|
|
Firstly, having a project allows metadata to be specified outside of a single
|
|
note's front matter, meaning that consistent rendering can be achieved without
|
|
cluttering up your documents. To do this, create a file "_quarto.yml" in
|
|
`g:mbnotes_dir`. I find this is a good place to start
|
|
|
|
>yaml
|
|
author: "{Your Name}"
|
|
format:
|
|
html:
|
|
embed-resources: true
|
|
html-math-method: katex
|
|
theme:
|
|
light: flatly
|
|
dark: darkly
|
|
pdf:
|
|
documentclass: article
|
|
geometry:
|
|
- top=25mm
|
|
- left=25mm
|
|
- heightrounded
|
|
<
|
|
|
|
Another benefit is that the output directory can be set inside "_quarto.yml",
|
|
and all build artifacts will be kept in one location. If this change is made,
|
|
please note that `g:mbnotes_out_dir` will also need to be updated to match.
|
|
This gives a convenient location to find built resources, as well as utilise
|
|
the caching features of Quarto.
|
|
|
|
==============================================================================
|
|
3. Creating Notes *mbnotes-creating*
|
|
|
|
3.1. New Notes *mbnotes-new*
|
|
|
|
`:MBNotesNew` *:MBNotesNew*
|
|
|
|
Creates a new note in the current window, with today's date in the file name.
|
|
The date used rolls over at |g:mbnotes_new_day_time|.
|
|
|
|
When this note is saved, it will expect to find at least one h1 element. If it
|
|
does, the file will be renamed with a sanitised version of that title. If it
|
|
does not, an error is thrown. Control this behaviour with
|
|
`g:mbnotes_rename_on_save`.
|
|
|
|
`:MBNotesNewSplit` *:MBNotesNewSplit*
|
|
|
|
The same as `:MBNotesNew`, but opens in a split. Can be controlled by modifier
|
|
commands, such as `:above`.
|
|
|
|
3.2. Daily Notes *mbnotes-daily*
|
|
|
|
MBNotes includes a daily note that can be used as a scratch pad, journal, or
|
|
really anything. If the flag `g:mbnotes_open_daily_on_startup` is enabled, this
|
|
daily note will open when Vim is opened. If it does not:
|
|
|
|
`:MBNotesDaily` *:MBNotesDaily*
|
|
|
|
Open a daily note in the current window. By default, this will open today's
|
|
note. However, this command takes a single optional integer argument
|
|
reprenting an offset. To open tomorrow's daily note >vim
|
|
|
|
:MBNotesDaily 1
|
|
|
|
Or to open last week's >vim
|
|
|
|
:MBNotesDaily -7
|
|
|
|
`:MBNotesDailySplit` *:MBNotesDailySplit*
|
|
|
|
The same as `:MBNotesDaily`, but opens in a split. Can be controlled by
|
|
modifier commands, such as `:vertical`.
|
|
|
|
3.3. Extracting Notes *mbnotes-extracting*
|
|
|
|
New notes can be created from any text within Vim. These will be put into a new
|
|
note as created by `:MBNotesNew`, which will be opened.
|
|
|
|
*gb*
|
|
<Plug>MBNotesNew{motion} Yank the text that {motion} moves over and put
|
|
it into a new note buffer.
|
|
|
|
*gbb*
|
|
<Plug>MBNotesNewLine{motion} Yank the current line into a new note buffer.
|
|
|
|
*v_gb*
|
|
{Visual}<Plug>MBNotesNew Yank the highlighted text into a new note buffer
|
|
(for {Visual} see |Visual-mode|).
|
|
|
|
These are not mapped to anything usable by default. To use these operators,
|
|
choose a suitable key sequence, and set it:
|
|
|
|
>vim
|
|
nmap gb <Plug>MBNotesNew
|
|
xmap gb <Plug>MBNotesNew
|
|
nmap gbb <Plug>MBNotesNewLine
|
|
<
|
|
|
|
==============================================================================
|
|
4. Rendering Notes *mbnotes-rendering*
|
|
|
|
Notes are normal Quarto documents, and as such can be rendered by Quarto into
|
|
anything. We include commands to render and open PDFs and HTML files. Rendering
|
|
can be customised by setting `g:mbnotes_quarto_binary` and
|
|
`g:mbnotes_quarto_render_args`.
|
|
|
|
`:MBNotesPDF` *:MBNotesPDF*
|
|
|
|
Render the current buffer as a PDF. It will open the PDF using
|
|
`g:mbnotes_open_command` if it successfully builds.
|
|
|
|
If the document fails to render, a terminal buffer is displayed showing the
|
|
results of the quarto render command that was attempted. To control when and
|
|
how a the terminal buffer showing rendering information is displayed, see
|
|
`g:mbnotes_renderer_show`, `g:mbnotes_renderer_close_on_end`, and
|
|
`g:mbnotes_renderer_buffer_command`.
|
|
|
|
`:MBNotesRenderHTML` *:MBNotesRenderHTML*
|
|
|
|
Render the current buffer as an HTML file and open it. See |:MBNotesRenderPDF|
|
|
for details on behaviour.
|
|
|
|
==============================================================================
|
|
5. Configuration *mbnotes-config*
|
|
|
|
g:mbnotes_out_dir *g:mbnotes_out_dir*
|
|
|
|
This is where rendered outputs will be placed. By default this is a temporary
|
|
directory, but it can be set manually.
|
|
|
|
>vim
|
|
let g:mbnnotes_out_dir = g:mbnotes_dir .. "/_output"
|
|
<
|
|
|
|
g:mbnotes_open_daily_on_startup *g:mbnotes_open_daily_on_startup*
|
|
|
|
When launching Vim with no additional arguments, open the current daily note
|
|
rather than the default Vim startup screen. Defaults to 0. Enable by: >vim
|
|
|
|
let g:mbnotes_open_daily_on_startup = 1
|
|
|
|
g:mbnotes_new_day_time *g:mbnotes_new_day_time*
|
|
|
|
Sets the time of day that a new day begins, as far as daily note designation is
|
|
concerned. By default, a new day starts at 4am, but to start a new day at
|
|
midnight, use >vim
|
|
|
|
let g:mbnotes_new_day_time = 0
|
|
|
|
g:mbnotes_date_format_short *g:mbnotes_date_format_short*
|
|
|
|
This date format is used in file names for new notes, and for daily notes. It
|
|
is recommended to keep this as something that sorts alphabetically. This string
|
|
should be something that can be passed to `strftime`. See `man 3 strftime` for
|
|
more details.
|
|
|
|
The default format outputs dates like "2023-09-21"
|
|
|
|
>vim
|
|
let g:mbnotes_date_format_short = "%Y-%m-%d"
|
|
<
|
|
|
|
g:mbnotes_date_format_long *g:mbnotes_date_format_long*
|
|
|
|
This date format is used to set the `date` metadata field in document front
|
|
matter, as well as the title for daily notes. See |g:mbnotes_date_format_short|
|
|
for formatting details.
|
|
|
|
The default format outputs dates like "Thursday, 18 May 2024"
|
|
|
|
>vim
|
|
let g:mbnotes_date_format_long = "%A, %-e %B %Y"
|
|
<
|
|
|
|
g:mbnotes_quarto_binary *g:mbnotes_quarto_binary*
|
|
|
|
Location of the quarto binary. By default, this uses whichever one is in $PATH.
|
|
|
|
g:mbnotes_open_command *g:mbnotes_open_command*
|
|
|
|
External command to open built files. By default, the following commands are
|
|
tried (in order):
|
|
|
|
* `open`
|
|
* `xdg-open`
|
|
|
|
If none of the above are defined, and this variable is not set explicitly, then
|
|
the render commands (e.g. `:MBNotesPDF`) will not open the output file
|
|
after rendering.
|
|
|
|
Explicitly set this to the empty string to disable opening behaviour.
|
|
|
|
g:mbnotes_renderer_show *g:mbnotes_renderer_show*
|
|
|
|
When a document is rendered, the quarto command to do so runs in a terminal
|
|
buffer. If this variable is true, the terminal buffer will be visible. By
|
|
default, the terminal buffer is not shown unless an error appears. >vim
|
|
|
|
let g:mbnotes_renderer_show = 1
|
|
|
|
g:mbnotes_renderer_close_on_end *g:mbnotes_renderer_close_on_end*
|
|
|
|
If `g:mbnotes_renderer_show` is true, then automatically close the renderer
|
|
buffer if it completes successfully.
|
|
|
|
g:mbnotes_renderer_buffer_command *g:mbnotes_renderer_buffer_command*
|
|
|
|
The command that should be used to open the renderer buffer, at any time. This
|
|
follows the default for terminal buffers opened by `term_start()` which is
|
|
`botright sbuf`. For example: >vim
|
|
|
|
let g:mbnotes_renderer_buffer_command = "vertical sbuf"
|
|
|
|
g:mbnotes_quarto_render_args *g:mbnotes_quarto_render_args*
|
|
|
|
An array of extra arguments passed to the command used to render documents. For
|
|
example, to always use the jupyter engine: >vim
|
|
|
|
let g:mbnotes_quarto_render_args = ["-M", "engine:jupyter"]
|
|
|
|
g:mbnotes_rename_on_save *g:mbnotes_rename_on_save*
|
|
|
|
This plugin will attempt to intelligently rename a note based on its title,
|
|
which is the first H1 that it finds in the document. Disable this behaviour by
|
|
setting this variable to false >vim
|
|
|
|
let g:mbnotes_rename_on_save = 0
|
|
|
|
It is not recommended to disable this without some other way of generating file
|
|
names.
|
|
|
|
==============================================================================
|
|
6. Integrations *mbnotes-integrations*
|
|
|
|
There are many different plugins that I use to help my notes work better. I
|
|
have packaged some of the integrations in this plugin, such that they will load
|
|
if those plugin are installed.
|
|
|
|
==============================================================================
|
|
6.1. UltiSnips *mbnotes-ultisnips*
|
|
|
|
This plugin packages a few UltiSnips snippets out of the box. These facilitate
|
|
creating Quarto front matter with a date and title, callout blocks (as per the
|
|
Quarto documentation), and fenced code blocks that Quarto will execute.
|
|
|
|
If you use UltiSnips and would not like these, create a file called
|
|
`mbnotes.snippets` in your snippets directory, and include a line: >snippets
|
|
|
|
clearsnippets
|
|
|
|
The snippets vended by this plugin are at priority -1, so should be cleared by
|
|
a default priority instruction. Furthermore, any of these snippets can be very
|
|
easily overwritten. See the `priority` keyword in |ultisnips-basic-syntax| for
|
|
more information.
|
|
|
|
==============================================================================
|
|
6.2. FZF *mbnotes-fzf*
|
|
|
|
A few commands are packaged that use FZF to open and search your notes.
|
|
|
|
`:MBNotes` *:MBNotes*
|
|
|
|
Lists all notes.
|
|
|
|
More specifically, all files within `g:mbnotes_dir`. The query is prefilled
|
|
with ".qmd$" to only find Quarto files.
|
|
|
|
`:MBNotesSearch [PATTERN]` *:MBNotesSearch*
|
|
|
|
Search all notes for the given pattern.
|
|
|
|
By default, this command depends on ripgrep being installed. The underlying
|
|
search query can be changed by setting `g:mbnotes_search_command`. [PATTERN] is
|
|
appended to that command.
|
|
|
|
`:MBNotesTags [TAG]` *:MBNotesTags*
|
|
|
|
Search all notes for a given tag using `g:mbnotes_search_command`.
|
|
|
|
vim:tw=78:ts=8:noet:ft=help:norl:
|