Taking notes, especially those that include terminal commands or code snippets, has always caused me a headache. Typically, I spend more time formatting the content than recording the information I need. The end result is often difficult to update and more importantly, awkward to extract terminal commands from. I needed a note taking solution that could achieve the following goals:
I’ve tried a few options but I’ve never been happy with the end result. Microsoft OneNote positions itself as a note taking application and there are many YouTube videos showing impressive medical notes that probably took hours to create. However, OneNote lacks the ability to create text formatting styles that can be applied consistently to your document. Every time you want to apply custom formatting you must select the font and size, choose the text colour and set the background colour. This is simply not an option when taking notes that include a terminal command or code snippet on every other line.
You can achieve a similar result by placing your terminal commands in a single cell table and setting the text attributes as before. Visually this works, however, attempting to reuse these commands by copying them often gives unexpected results and commands that no-longer execute.
Google Docs could also be used; however, syntax highlighting is not natively available. The Code Blocks plugin aims to solve this problem by automatically detecting the language your commands are written in and applying the corresponding syntax highlighting. Under the hood, the plugin is performing a OneNote-style formatting trick by creating a single cell table and applying the required formatting. Whilst this works, the same problems exist: it’s difficult to copy the commands and the process of setting the formatting through the plugin requires a number of steps.
Like Google Docs, Microsoft Word is a word processor designed to produce high quality documents with rich formatting. Whilst keyboard shortcuts can increase the efficiency of applying formatting to your text and objects, it is still an involved process with functionality buried within sub-menus. Pasting terminal commands or code snippets directly into Word is certainly possible but the user should be prepared for a spatter of red, drawing their attention to the multiple spelling errors Word has supposedly found.
Markdown is a simple markup language used for creating formatted text using a basic text editor. Spoiler: this blog entry was written using Markdown. Markdown takes the complexities of formatting and represents them in simple, text-based characters. For example:
Bold Text
Italic Text
blockquote
Inline Code
The underlying Markdown text for the above formatting is as follows:
# H1
## H2
### H3
**Bold Text**
*Italic Text*
> blockquote
`Inline Code`
The full Markdown cheat-sheet can be found here. A common assumption with Markdown is that images cannot be included, this is not the case. Images can be included using the following syntax:
Markdown doesn’t require a specific application or OS, it’s a language that can be written using an application as simple as Notepad or Mousepad. To immediately begin writing in Markdown, visit markdownlivepreview.com and enter your text and formatting characters on the left and watch them rendered on the right.
Popular purpose-built applications include source code editors such as: Sublime Text, Notepad++ or Atom. All can be configured to spell check Markdown files (.md extension), while Sublime Text goes a step further by including a built-in file manager.
Markdown meets many of the goals listed above:
By trade, GitHub is a web-based version control system (based on Git) that allows developers to store their projects and collaborate with others. GitHub uses Markdown for its documentation and can be accessed from any device with a web browser. Consequently, you can store Markdown files on GitHub, access and edit them from anywhere and leverage version control if required. Files stored on GitHub can be synchronised to a local machine using GitHub Desktop for Windows, or the Git client on Linux (apt install git). Updates made on your local machine can then be ‘committed’ and pushed to your remote GitHub repository.
GitHub is free but also offers paid subscriptions offering additional features and storage. GitHub Pages utlises a GitHub repository to create web pages whose content is rendered from Markdown files. The MSR-Sec.com website is based on this feature, see pages.github.com](https://pages.github.com/) for further details.
I’ve agonised over my note taking method a number of times, most recently while studying for my OSCP where I resorted to OneNote. Striking a balance between efficiency and functionality has been difficult to find, having only recently become aware of Markdown and GitHub. The simplicity and effectiveness of Markdown is its key strength making it suitable for many publications. Documentation, blog posts, forum messages and an entire book have all been written in Markdown, proving its versatility and accessibility.