*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 `MBNotesNew`, and a normal mode mapping to `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: