My Digital Garden

What is a Digital Garden?

A digital garden is a mix between a notebook and a blog, it is a place to share thoughts and cultivate them into a garden. It also allows me to have a place where I can store my notes/summaries/tutorials for my studies.

The main difference to a blog is that a blog has articles and publication dates and never changes after it has been published, whereas a digital garden is a place where the written content can be continuously edited and refined. The notes are also very free flowing they can span from just a short cheatsheet to a full set of notes on an entire subject where you go into every nitty-gritty detail.

Another key difference is the navigation. A blog is usually read in chronological order but a digital garden can be read in any order you want and uses lots of internal links to connect all the notes into a Network (although this can be quite hard to diligently do).

If you are interested in learning more about digital gardens I can recommend the following article by Maggie Appleton (opens in a new tab).

How is my Garden Built?

The current iteration of my digital garden is built using Nextra (opens in a new tab). Nextra is a static site generator that is built on top of Next.js and MDX. This allows me to write my notes in markdown and also use the MDX format to write JSX in my markdown files. These markdown files are then converted into static HTML files using Next.js and can be hosted on any static site hosting service such as Vercel (opens in a new tab).

The Features

In this section I briefly go over some of the features that are supported by my digital garden and how to use them.

Markdown

Markdown is supported out of the box. Anything that is supported by markdown can be used in the notes. This includes but is not limited to:

• Headers
• Lists
• Links
• Images
• Code Blocks
• Tables
• Blockquotes

For a full list of markdown features check out the Markdown Guide (opens in a new tab).

MDX

In addition to the normal markdown format, Nextra also supports the MDX format which allows you to write JSX, i.e. react code in a markdown file. To find out more about MDX check out the official MDX documentation (opens in a new tab).

Admonitions / Callouts

Admonitions aren't included in standard markdown but have become very popular. Recently GitHub has also added support for admonitions in markdown FileSystem, however they call them alerts.

Admonitions are very useful to highlight certain text and add a category to the text. I have added a custom component that builds on nextra's callouts to be able to add custom callout types. To use callouts in a MDX file you can use the following syntax:

<Callout type="warning">
This Is a big scary warning.
</Callout>

Renders to:

You can also change the title of the banner:

<Callout type="info" title="The following types are supported">
info, warning, error, example, todo
</Callout>

The default callout type uses the websites primary color, a rocket icon and has no title:

Jupyter Notebooks

LaTeX

It has recently become very popular to write LaTeX equations in markdown. Nextra supports this by using KaTeX (opens in a new tab). You can render LaTeX content either inline between $\LaTeX$ $\LaTeX$ or as a block between $$I = \int_0^{2\pi} \sin(x)\,dx$$:

Annoyingly Jupyter Notebooks use MathJax to render LaTeX content in the same way instead of KaTeX. This means that KaTeX supports some things and MathJax supports other things. Importantly however is that the Jupyter Notebooks get converted to Markdown and therefore in the end it will only be rendered in KaTeX.

Therefore, if something is written that is supported in MathJax but not in KaTeX it might look okay but in the end, it will not be rendered by KaTeX. This leads to my LaTeX Notation Guideline to avoid conflicts whilst still keeping nice Formulas.

You can see what is supported by KaTeX here, (opens in a new tab) and you can see what is supported by MathJax here (opens in a new tab).

PlantUML

If you ever need to create diagrams and especially UML diagrams, PlantUML is the way to go. I started with Mermaid to create UML diagrams but swapped to PlantUML for the additional features and the ability to create custom themes (so everything can be minimalist and purple :D).

To render PlantUML diagrams the Remark plugin Simple PlantUML (opens in a new tab) is used which uses the official PlantUML server to generate an image and then adds it.

An Example can be seen below, on the official website (opens in a new tab) and also on REAL WORLD PlantUML (opens in a new tab).

To use my custom theme you can use the following line at the beginning of the PlantUML file:

@startuml
!theme purplerain from http://raw.githubusercontent.com/LuciferUchiha/georgerowlands.ch/main

...

@enduml

However, it seems like when using a custom theme There can not be more then one per page? My custom theme also has some processes built in for simple text coloring for example in cases of success, failure etc.

How can I Contribute?

Do you enjoy the content and want to contribute to the garden by adding some new plants or watering the existing ones? Then feel free to make a pull request. There are however some rules to keep in mind before adding or changing content.

• Markdown filenames and folders are written in camelCase.
• Titles should follow the IEEE Editorial Style Manual (opens in a new tab). They should also be added to the markdown file and specified in the _meta.json which maps files to titles and is also responsible for the ordering.
• LaTeX should conform with my notation and guideline, if something is not defined there you can of course add it.