297 lines
11 KiB
Text
297 lines
11 KiB
Text
*mbnotes.txt* Max Bucknell's notes framework
|
|
|
|
==============================================================================
|
|
1. Contents *mbnotes-contents*
|
|
|
|
1. Introduction ...................... |mbnotes|
|
|
2. Setup ............................. |mbnotes-setup|
|
|
3. Configuration ..................... |mbnotes-config|
|
|
4. Commands .......................... |mbnotes-commands|
|
|
4.1. Operator .................... |mbnotes-operator|
|
|
5. Front Matter ...................... |mbnotes-front-matter|
|
|
6. Integrations ...................... |mbnotes-integrations|
|
|
6.1. UltiSnips ................... |mbnotes-ultisnips|
|
|
|
|
==============================================================================
|
|
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.
|
|
|
|
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.
|
|
|
|
==============================================================================
|
|
3. 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. If the project `output-dir` is set in
|
|
the Quarto project `_metadata.yml` like so:
|
|
|
|
>yaml
|
|
project
|
|
output-dir: _output
|
|
<
|
|
|
|
Then `g:mbnotes_out_dir` should be set accordingly:
|
|
|
|
>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_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. |:MBNotesRenderPDF|) will not open the output file
|
|
after rendering.
|
|
|
|
Explicitly set this to the empty string to disable opening behaviour.
|
|
|
|
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
|
|
|
|
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_quarto_binary *g:mbnotes_quarto_binary*
|
|
|
|
Location of the quarto binary. By default, this uses whichever one is in $PATH.
|
|
|
|
==============================================================================
|
|
4. Commands *mbnotes-commands*
|
|
|
|
`: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|.
|
|
|
|
`:MBNotesNewSplit` *:MBNotesNewSplit*
|
|
|
|
The same as `:MBNotesNew`, but opens in a split. Can be controlled by modifier
|
|
commands, such as `:above`.
|
|
|
|
`:MBNotesOpenDaily` *:MBNotesOpenDaily*
|
|
|
|
Open the daily note in the current window. This command takes a single optional
|
|
integer argument reprenting an offset. To open tomorrow's daily note >vim
|
|
|
|
:MBNotesOpenDaily 1
|
|
|
|
Or to open last week's >vim
|
|
|
|
:MBNotesOpenDaily -7
|
|
|
|
`:MBNotesOpenDailySplit` *:MBNotesOpenDailySplit*
|
|
|
|
The same as `:MBNotesOpenDaily`, but opens in a split. Can be controlled by
|
|
modifier commands, such as `:vertical`.
|
|
|
|
`:MBNotesRenderPDF` *:MBNotesRenderPDF*
|
|
|
|
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.
|
|
|
|
`:MBNotesRenderHTML` *:MBNotesRenderHTML*
|
|
|
|
Render the current buffer as an HTML file and open it. See |:MBNotesRenderPDF|
|
|
for details on behaviour.
|
|
|
|
==============================================================================
|
|
4.1 Operator *mbnotes-operator*
|
|
|
|
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*
|
|
gb{motion} Yank the text that {motion} moves over and put it into a
|
|
new note buffer.
|
|
|
|
*gbb*
|
|
gbb Yank the current line into a new note buffer.
|
|
|
|
*v_gb*
|
|
{Visual}gb Yank the highlighted text into a new note buffer (for
|
|
{Visual} see |Visual-mode|).
|
|
|
|
These mappings are only set if `gb` is not already mapped to something. If they
|
|
are, or if you wish to customise these mappings, create new normal and visual
|
|
mode mappings (`nmap` and `xmap`) to `<Plug>MBNotesNew`, and a normal mode
|
|
mapping to `<Plug>MBNotesNewLine`.
|
|
|
|
==============================================================================
|
|
5. Front Matter *mbnotes-front-matter*
|
|
|
|
Quarto supports a wide variety of configuration for document metadata. This can
|
|
be placed in the document front matter, but it gets unwieldy. It is recommended
|
|
that `g:mbnotes_dir` point to a Quarto project. Then, a file called
|
|
`_metadata.yml` can be placed at the root.
|
|
|
|
A good place to start is:
|
|
|
|
>yaml
|
|
author: "{Your Name}"
|
|
format:
|
|
html:
|
|
embed-resources: true
|
|
html-math-method: katex
|
|
theme:
|
|
light: flatly
|
|
dark: darkly
|
|
pdf:
|
|
documentclass: article
|
|
geometry:
|
|
- top=30mm
|
|
- left=20mm
|
|
- heightrounded
|
|
<
|
|
|
|
Anything supported by Quarto can be specified here and will be imported and
|
|
merged with any front matter specified at the top of any file. See the Quarto
|
|
docs for more information, specifically on projects.
|
|
|
|
==============================================================================
|
|
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. Snippets *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.
|
|
|
|
vim:tw=78:ts=8:noet:ft=help:norl:
|