While it's not something that everyone likes to do, I've always found it essential to write notes. There are the project-specific notes that only have relevance within a particular workplace and are of course confidential, but then the stacks of notes that cover everything from the content of the training course you last went on to "what's the command-line way to add a new project again?" - and that second category is the one we're going to discuss here.
Besides good old pen and paper I've tried all sorts, with tools like Evernote, Keep, the original Catch Notes (RIP), and Apple Notes each having very different levels of support for formatting, embedding, and crucially, portability of stored data. The latter becomes especially significant if the service closes down, or if (in the case of Apple Notes) you hand back the computer at the end of a job. As I looked at the pages of pencilled notes I'd written while following an online tutorial recently, I realised that a more unified and durable approach would be extremely useful. A solution flashed into my head while updating the wiki for a personal project on Bitbucket - why not have a private repo consisting entirely of Markdown notes, rather than code?
Benefits
- Markdown is familiar to a large proportion of developers, is easy to write, and widely-supported - but also fairly readable even as plain text without a parser.
- Markdown has great support for inserting the kinds of things we so often need - code snippets, links, tables, and multi-level bullet lists - with minimal effort, allowing you to concentrate on the content.
- Using a Git repo makes it easy to quickly sync the notes across machines.
- This approach removes the reliance on proprietary sites. As each copy of the repo is just the same as any other, even the loss of your online Git account is not catastrophic.
Basic Structure
The root of the repo has an index.md file, with each overall topic being contained in a folder - and each of these also contains an index.md. If it's a big enough topic, there might be an extra level, but the aim is just organised enough without having a crazy directory tree structure.
The root index.md contains links to the index files in each folder.
Those index files, in turn, link to other .md files within their own directories for each article.
Article Content
The beauty of this being your private repo is that you're not beholden to any particular standard - you can be free to write in as formal or as loose a way as you'd like. At some times you might have nothing but a raw text braindump, at others you may have topics that you can write on in a more structured way. The point that is central is that you write in the way that works for you, in the terms that make it the most useful for the way you read, think, and recall.
Code snippets (with the original spacing preserved) and shell commands can be inserted easily, as can links to external resources that might be useful for each topic.
In addition, now that everyone has a camera in their pocket, diagrams can be sketched, photographed, and included as inline images, rather than being laboriously reproduced with a computerised drawing tool.
As an aside, if you need to copy/paste formatted text from other document formats, PuppyPaste is a very handy tool which will convert the formatting to the Markdown equivalent, which you can then copy/paste/edit as necessary.
Reading
The main online Git sites will support the viewing of Markdown files, but if you want to view them outside of this framework then a small amount of extra work is needed. As web browsers don't generally have native support for Markdown files, you can't get the benefit of using one as a viewer directly, but some very kind people have provided solutions to this. Someone recommended MDwiki and having used it, I will too.
Simply download the HTML file into the root of your repo, and rename it to index.html. Pointing a web server at this folder (I wrote an absolutely minimal one with Node.js and Express) makes it an HTML web-browsable wiki.
Uses and Conclusion
I now have copies of my own repo on a Windows desktop, Mac laptop, and a USB flash drive, as well as on Bitbucket. A quick git pull on each grabs the latest changes as needed, and after that the notes are available even if there is no network available. I'll be continually adding to it and think that this is a solid way of preserving the jewels picked up along my development journey. I hope some of you find this approach useful too!
Top comments (22)
I learned of Obsidian last week from harshibar. It looks promising, unfortunately, it doesn't recognize .markdown as a Markdown file. :-(
From my limited testing, it looks like it could be useful, especially being able to create links.
Thanks for the tip!
+1 for Obsidian. Nice and simple and portable (I have it on Mac and Windows). Oddly, never occurred to me to put all the notes i have scattered EVERYWHERE into a git repo!
I did this too but thought instead of making it private why not make it public. Seems like every developer I know does this in some way.
I started a project a couple weeks ago to fix this problem. It’s in the concept phase so a lot of design can change. I’m looking for some feedback so if you want to check it out that would be great. :)
syntaxrecall.dev
github.com/syntaxrecall/syntaxrecall
I've actually never known another developer do this (or if they have, they've been quiet about it), but I guess writing about it attracts other people who think the same way!
Making content public or private is down to personal choice of course, but I think there's something to be said about removing the pressure of the public gaze and tailoring the content to exactly what you need. There's also a benefit if you want to use code snippets/examples/diagrams (or entire topics) that you explicitly don't want to share for whatever reason. However, using an open source format like MD means that it's very easy to port content out from one repo to another if there's something to share more widely.
Thanks for the link! I tried to launch the site itself but couldn't get it to respond to any searches - are there any pre-requisites for the browser running it?
Some of the devs I've worked with use cacher.io/. I tried it, but I didn't want to pay for it. I like the personal wiki approach but I prefer the devhints.io approach more. Everyone can contribute and knowledge share. Saves everyone time, making everyone more productive.
For my site yeah there's not much content currently cause I just started it. Try searching for one of these though.
Cheatsheets
Tools
Love the idea of browsing & viewing the notes on a browser!! I have been using markdown + VSCode + git for my notes for over 4 years now. Absolutely love it!!
I will give it a try on MDWiki!! Thanks for the great post!!
Thank you! I love that you've got your actual daily project notes there too - great for recalling design decisions from the distant past :)
Hi, Adam. Thanks for the tip about MDwiki. I'm going to look into that.
I have recently started my own TIL repository on GitHub following several of the concepts that you described. I don't have much there yet, but it seems to be a good fit for me so far. Check it out and let me know what you think.
If you don't mind check these out and give me some feedback. :)
syntaxrecall.dev/vscode-keyboard-s...
syntaxrecall.dev/vim
Looking good! I'll definitely be making use of some of those VS code shortcuts.
(as an aside, it is a classic of dev life that you need a cheat sheet to exit
vi🙂)I like where you're going with that! I might borrow the idea of having a section specifically for tools - little cheat sheet pages that would be really useful on a second monitor 👍🏿
it sounds like foam might be for you: it uses exactly your type of markdown and file based layout, while simplifying the process of linking content. All while being a VSCode plugin.
I recently started using it and must admit that I'm hooked 🤷♂️
Like it. What's your process of adding images to the pages? Is it: take a picture with a smartphone → icloud/dropbox sync to computer → move the file to the repo → add an image in markdown?
I'm yet to find a perfect solution for a personal knowledge base. I like to add diagrams next to the text (often a doodle is worth a hundred words) and I want the process to be as easy as possible. I found Notability app to serve best my needs. Using it on my iPad and computer. Also tried OneNote, GoodNotes and (Apple) Notes but they didn't click with me.
Thank you! Yes, that's basically the process for adding images - I've only had to do that with one or two hand-drawn ones so far, for screenshots it's of course even simpler than that.
When I was first introduced to Apple Notes, I got into using it but getting the information out was ridiculous - I ended up connecting it to my Google account and so the notes now live in a Gmail folder as though they're emails. I've started the process of copying/reformatting the info to live in this repo, where it'll be a bit more useful!
If you want a super easy http server, python has one built in. Just go to the directory and run this:
python3 -m http.serverThat's a great tip! 👍🏿
Also - try Notational Velocity if you're on macOS
Like your idea. Honestly, there is really no need to do website to collect something. Never thought about "just repository" as about a knowledge base!
MDwiki is stopped maintain.
And when I tried with ver 0.6.2, it doesn't show up anything, error
imgur.com/isDChd9
can you have a look!?