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