Garden

🚧 Under reconstruction.

This is my digital garden.

A digital garden is like a personal knowledgebase. It is a space for managing your knowledge in your professional domain. This is done by cultivating a structured collection of bookmarks, notes, thoughts, and ideas.

A digital garden is a perpetual work-in progress. It is a series of living documents that each need to be regularly tended. Like a regular garden, a digital garden needs careful planning. You need to be selective about what things you add to it and what you omit. You need to think about how everything will be arranged. In time, new living documents may be planted, and older ones weeded out.

For more background, see Maggie Appleton’s excellent essay on the concept of the digital garden.

In my digital garden, my preference is for atomic documents formatted in AsciiDoc. Each .adoc file is focused on a single idea or concept. Topics may cross-reference one another, but otherwise each file is a self-contained document. Topics are concentrated around my own areas of professional expertise – computer programming, and system design and architecture – but they also branch out into other areas of information technology.

Legend

  • 🌱 Seedling: Early draft.

  • 🌿 Budding: Needs attention.

  • 🌳 Evergreen: Mature document.

  • 🍂 Decaying: No longer maintained.

Contents

Core topics

The following topics are "tent poles" that link out to most other topics.

Hot topics 🔥

I’m actively researching these topics at this time:

All topics

0-9

A

B

C

D

E

F

G

H

I

J

K

L

M

N

O

P

Q

R

S

T

U

V

W

Y

Requirements

Some documents in my Digital Garden embed PlantUML notation.

To render PlantUML diagrams in AsciiDoc, you will need to have a PlantUML server running. It is RECOMMENDED to use Kroki, a free web service that renders diagrams and charts from text representations, not only in the PlantUML DSL but also Mermaid, Graphviz and many others.

In VS Code, add the following setting to your settings.json file – either at the workspace or user level. This will enable the Kroki extension for AsciiDoc and use the free public Kroki server.

{
  "asciidoc.extensions.enableKroki": true,
  "asciidoc.preview.asciidoctorAttributes": {
    "kroki-server-url": "https://kroki.io",
  },
}

You can also run a local Kroki server. The full instructions are here, but basically it involves pulling and running a Docker container based on the official Kroki image:

# If you haven't done this before, pull the Kroki server image from Docker Hub.
# https://hub.docker.com/r/yuzutech/kroki
docker pull yuzutech/kroki

# Run a container based on this image. Run the container in detached mode (-d)
# and map the container's port 8000 to your local machine's port 8080.
docker run -d -p 8080:8000 yuzutech/kroki

Go to http://localhost:8080/ to verify that the Kroki server is running. Then change your settings.json to point to the local server instead.

{
  "asciidoc.extensions.enableKroki": true,
  "asciidoc.preview.asciidoctorAttributes": {
    "kroki-server-url": "http://localhost:8080",
  },
}

For AsciiDoc, the PlantUML DSL code needs to be embedded within literal blocks. If you have everything configured correctly, you should be able to see the rendered diagram below, when viewing this document in preview mode.

@startuml
entity person {
* id: INT <<FK>>
* name: VARCHAR(128)
---
address: VARCHAR(256)
email: VARCHAR(128)
phone: VARCHAR(16)
}
@enduml

If you can see the Kroki landing page via http://localhost:8080 in you web browser, but the diagrams do not generate in AsciiDoc preview in VS Code, first try restarting VS Code. If that doesn’t work, try adjusting the security settings. Open VS Code’s command palette (Ctrl+Shift+P), select "AsciiDoc: Manage Preview Security Settings", and choose "Allow insecure local content".