Technical overview

Below are some bullet points that provide an outline of what’s under the hood of this site you are looking at.

• All content is written with vim, my editor of choice
  • vim plugins used
    • I use vimwiki to write all the notes and posts and pages
    • CtrlP is used to quickly jump between existing files
      • However, I just (re)discovered fzf for finding files and it looks fantastically promising.
        • Apparently, coupled with ripgrep, it could be a real game changer for switching files and finding text in a project
        • see Unix is my IDE – mkaz.blog
• The site is statically generated in two stages
  • First stage (writing the wiki)
    • uses vimwiki to export markdown pages written with vimwiki to prepare markdown files for stage 2 page generation with Jekyll
    • first stage uses vimwiki’s Vimwiki2HTML command whenever a file is saved
      • saves existing markdown files in the wiki
        • when a file is saved, the Vimwiki2HTML command is automatically called
        • files are converted and saved to my _notes directory within Jekyll directory as well as the wiki directory
      • the command typically outputs markdown files to HTML with an .html extension
        • however, you can tell the command to use a custom script instead.
          • this allows you to convert and save the files however you like
            • I wrote a custom perl script markdown_to_note that performs the custom conversion
              • it fixes links so they don’t break in Jekyll
              • it adds a header to the markdown pages for processing by Jekyll
              • it generates bidirectional links
                • bidirectional links are an important feature for helping uses navigate content
                  • see A Short History of Bi-Directional Links
              • other misc. stuff
  • Second stage
    • I run a bash script manually when I’m ready to make an update to the production site
    • The script statically generates the site with Jekyll to produce a final product and pushes it up to the hosting platform
    • Jekyll now converts the markdown files generated by my Perl script in stage one into html files that can be posted on the web.
    • I am new to Jekyll, so can’t provide much detail on it other than:
      • It’s written in Ruby
      • It does not require a database
      • It’s essentially a program that takes files written in markdown and converts them to static HTML files.
• Site is hosted for for free using GitHub Pages
  • Since it’s on GitHub, all changes are tracked
    • The files are generated on my local machine and then pushed out to my GitHub repository
• The theme is not my own and was forked from https://github.com
  • I have made some fairly modest changes to original forked code

Cool Features of My Configuration

Over the past week or so, I’ve developed some great features to greatly speed my workflow. It’s pulled off with a patchwork of relatively simple perl modules, bash scripts, and a slightly advanced vim configuration. I describe some of them here:

Synchronized browsing

• If I’m editing a note in vim, I can type <leader>gv in vim and the page I’m editing will open in Safari and it will look exactly like it will look like when I publish it. This gives me a live preview of my markdown pages and I can see how it will look on the web before publishing it.
  • The site run locally on my machine thanks to Jekyll’s built-in server that it provides
  • By default, site is accessible at http://127.0.0.1:4000
• This works the other way. If I navigate to any page in my browser, I can type <leader>gb and vim will open the corresponding markdown file will appear in the buffer. Nice!

URL insertion

• If I’m reading a web page and I want to add a link to it, I just hit <leader>gg and vim will automatically insert a properly formatted markdown link along with the title (grabbed from the HTML source code) into my document.
  • Huge time saver
  • See Insert hyper links for documentation

Other notes linking here:

Tech stuff

Diary entry for 2020-07-17