I started taking all of my notes in markdown a few years ago, including my Zettelkasten1. I like it because it’s easy, fast, and pretty much standard nowadays. But rendering, then publishing and navigating the rendition of a folder structure is surprisingly cumbersome. Either you need to rely on a UI that generate the HTML, or on a heavy and opinionated platform like Jekyll or Hugo. That’s why I built plaf.

Plaf is a low profile markdown “website”2 generator. The main goal is for it to be non-intrusive: you just run plaf in a folder that contains markdown notes, and you obtain an HTML rendition that can be browsed. It generates indexes of folders, and renders the markdown notes. Plaf can also act as an HTTP server using plaf --serve.

There are a few additional goals that I wanted to achieve with plaf:

  1. all output must be static, I don’t want an application server to see the results
  2. have some form of search engine fully implemented on the client side. Since one of my goals was to render my knowledge base, being able to search is primordial. I’m using Lunr for that purpose. When you go to the search page, the catalog is loaded on the client, which actually makes it pretty fast. Example. plaf --generate-search
  3. some of the stuff on my KB I want to access publicly, but I want password protected. And so plaf supports AES encryption and client-side decryption of generated pages. In this case the content is generated as a base-64 encoded cryptogram that is loaded into an HTML page, and decrypted if you provide the right password. It also offers to save the password locally to decrypt automatically when you reload the page or website. Either plaf --password which encrypts the whole website, or use a password: xxx in the front-matter yaml header. To be honest, I’m pretty proud of that mechanism, I find it very cute.
  4. lightweight optional support for templates based on Mustache3.
  5. support tags and wiki-links to allow non-hierarchical navigation
  6. serve files dynamically, in case I just want to browse my work notes without generating the pages plaf --serve.

There might be a few other features like pagination I want to support in the future. I’ve also toyed with the idea of switching that blog to plaf ; but I don’t want it to become too heavy, and it’s not meant to be a blog engine, so we’ll see.

If you want to use it you need NodeJS, then install from the npm package using npm install -g plaf, and run by calling plaf in the source folder. It creates an output folder containing the HTML. If you want to see it in a browser, use plaf --serve, or use a server such as Apache, Nginx (yeah, yeah…).

The whole thing is built in Javascript and the code is available here. It uses a pipeline that gets modified based on what options you select.

Notes

  1. Card-based Knowledge management - see mine 

  2. In quotes because the goal is absolutely not to create marketing websites, but really renditions of something in a text format into a browseable HTML format. 

  3. Using handlebars