How to Make a Blog Like This

Be correct

I always ask myself these questions:

Who is the authority on this?
Is someone being paid to be correct?
Does this activity have a following, group, conference, forum, or discord?
Can this be tested in the lab?
Can this behavior be observed?
Can the behavior be documented?
Can the behavior be diagrammed?
Is effort tracked by a standards body? e.g., the IETF, IEEE, etc.

See The Correctness Hierarchy.

Documentation as code

This blog follows the Documentation as Code ethos.

Create an account on GitHub
Write articles in Markdown
Learn Git Fundamentals
Use Git
Use a development environment
Use GitHub Pages and Actions to Deploy mdBook
- My Deploy script on GitHub

My development environment

I use Notepad++ with Syncthing.

When I save a file in Notepad++, Syncthing is notified of the change and propagates it to tesseract. mdBook sees the modification and rebuilds the webpage.

ariadne@tesseract:~/git/pushpopswap$ mdbook serve -n 0.0.0.0
 INFO Book building has started
 INFO Running the html backend
 INFO HTML book written to `/home/ariadne/git/pushpopswap/book`
 INFO Serving on: http://0.0.0.0:3000
 INFO Watching for changes...
 INFO Files changed: ["/home/ariadne/git/pushpopswap/src/how-to-make-a-blog-like-this.md"]
 INFO Book building has started
 INFO Running the html backend
 INFO HTML book written to `/home/ariadne/git/pushpopswap/book`
 INFO Files changed: ["/home/ariadne/git/pushpopswap/src/how-to-make-a-blog-like-this.md"]
 INFO Book building has started
 INFO Running the html backend
 INFO HTML book written to `/home/ariadne/git/pushpopswap/book`

Processing

mdBook is used to turn CommonMark into html.

These tools extend the html features, typically with JavaScript.

Preprocessing

These are tasks mdBook cannot do without addons.

Mermaid

Javascript
Turns text into diagrams
Allows version control for diagrams
SVG Adaptive
- Resize Nicely
- Light and Dark theme adaptive

Mermaid is a binary js file that gets copied to the root of the repo.

curl -sL https://cdn.jsdelivr.net/npm/mermaid@11.5.0/dist/mermaid.min.js -o mermaid.min.js

Then mdbook needs to be rebuilt:

mdbook build

GitInfo

Injects Git Metadata into the rendered HTML articles
- Commit
- Date of Commit
- Link to Commit
- Onto every webpage

SVGBOB

buggy
Converts ASCII Art to a SVG
It does this on build

mdbook-svgbob uses the above embed svgbob into mdBook

Keyboard shortcuts