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
There are a few additional goals that I wanted to achieve with plaf:
- all output must be static, I don’t want an application server to see the results
- 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.
- 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 --passwordwhich encrypts the whole website, or use a
password: xxxin the front-matter yaml header. To be honest, I’m pretty proud of that mechanism, I find it very cute.
- lightweight optional support for templates based on Mustache3.
- support tags and wiki-links to allow non-hierarchical navigation
- serve files dynamically, in case I just want to browse my work notes without generating the pages
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…).