blog

Tips

(originally published February 12, 2020)

Pictures

The author as a younger man

Twitter

I did a thing and it got posted.

Link to a post

By reference:

Welcome back!

Or a specific link in a page. This uses the fact that markdown adds an automatic ref to titles:

Blogging title

Use the github shortcode to link to files in your GitHub repository. The repo URL is configured in config.toml as params.githubRepo.

Basic usage (defaults to main branch):

1

[`blog.go`]({{< github path="blog.go" >}})

Link to a specific branch:

1

[README on develop]({{< github path="README.md" branch="develop" >}})

Link to content files:

1

[This post's source]({{< github path="content/blog/tips/index.md" >}})

This generates URLs like https://github.com/dvhthomas/blog/blob/main/blog.go.

A gist on Github

Code snippet

If you include code inline you also get the ability to highlight lines:

1
2

$ echo "hello world"
hello world

But practically speaking it may be easier to include code from files that live in the same directory as the index.md for each post.

For example the file hello.py is in the same directory as tips.md. We can display it using

hello.py

1
2

def hello(who):
    print(f"hello {who}")

Diagrams

Mermaid

The YAML front matter contains mermaid: true and then this will render a nice diagram.

graph TD; t(top node) note t-->B;

D2

D2 is a modern diagram scripting language. Create a .d2 file in the same directory as your post, then reference it using the d2 shortcode.

For example, here’s a simple workflow diagram defined in example.d2:

D2 diagram from example.d2

The D2 source looks like this:

start -> process: step 1
process -> end: step 2

Reference it in your markdown with:

{{< d2 src="example.d2" >}}

Include an optional width: xx% to control the diagram’s width. For example:

{{< d2 src="example.d2" width="85%" >}}

Controlling diagram width

By default, D2 diagrams scale to 70% of the container width. You can override this with the width parameter:

  • Default (70%): {{< d2 src="diagram.d2" >}}
  • Full width (100%): {{< d2 src="diagram.d2" width="100%" >}}
  • Half width (50%): {{< d2 src="diagram.d2" width="50%" >}}
  • Custom: {{< d2 src="diagram.d2" width="85%" >}}

Use wider widths for complex flow diagrams, and narrower widths for simple hierarchical diagrams.

Reference URLs

You can avoid typing a URL multiple times by using a reference-type URL. Use either a numbered footnote style for whatever text. Or specific text that matches the link text itself.

Math

Set mathjax: true in the front matter. Then use either the ${inline}$ for or block form using two \$\$:

$$\large CAGR = \left( V_{final} \over V_{begin} \right)^{1/t} - 1 $$

Construct formulae using the $\LaTeX{}$ reference for math. Use the great reference on Overleaf for lots of worked examples. And this StackExchange Math articles is superb.

Charts

Using vega-lite.

Create a .json file with your Vega-Lite specification in the same directory as your index.md, then reference it using the vega shortcode.

For example, this chart references tips.json in the same directory:

The shortcode takes two parameters:

  • id: A unique ID for the chart div (e.g., viz, chart1, etc.)
  • spec: The filename of the JSON spec in your page directory (e.g., tips.json)

No front matter configuration needed - the shortcode is self-contained and loads Vega-Embed automatically.


View page source