*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| 6.3. Asyncomplete ................ mbnotes-asyncomplete ============================================================================== 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* MBNotesNew{motion} Yank the text that {motion} moves over and put it into a new note buffer. *gbb* MBNotesNewLine{motion} Yank the current line into a new note buffer. *v_gb* {Visual}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 MBNotesNew xmap gb MBNotesNew nmap gbb 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`. ============================================================================== 6.3. Asyncomplete *mbnotes-asyncomplete* Completion is supported via asyncomplete, for links to other notes. To enable this, include: >vim autocmd User asyncomplete_setup { asyncomplete#register_source( asyncomplete#sources#mbnotes#get_source_options({ 'priority': 9 }) ) } < This completion support depends on ripgrep being installed. vim:tw=78:ts=8:noet:ft=help:norl: