blog

Articles at https://dancroak.com

Setup

Install Go. Then, run:

go install ./...

This installs a blog command-line program from main.go:

usage:
  blog add <article-url-slug>
  blog serve
  blog build

It expects a file layout like this:

.
├── articles
│   └── example.md
├── code
│   └── example.rb
├── images
│   └── example.png
└-─ theme
    ├── public
    │   └── favicon.ico
    ├── article.html
    └── index.html

Write

Add an article:

blog add example-article

Edit articles/example-article.md in a text editor. It is a GitHub-Flavored Markdown file with no front matter.

The first line of the file is the article title. It must be an <h1> tag:

# Example Article

Preview at http://localhost:2000 with:

blog serve

Embed code blocks from external files into Markdown like this:

```embed
code/example.rb instantiate
```

This embeds code from code/example.rb between begindoc and enddoc magic comments with an id instantiate:

# begindoc: instantiate
require 'example-sdk'

client = Example::Client.new(
  credential: '...',
  name: 'example',
)
# enddoc: instantiate

This way, external files whose code is embedded in the Markdown prose can be run, linted, or tested in CI.

If you want to embed the whole file, no magic comments are needed:

```embed
code/example.rb
```

Add images to the images directory. Refer to them in articles:

![alt text](/images/example.png)

Modify theme

All theme/public files are copied to public.

The theme/index.html template is pure HTML. It is up to the author to decide how to lay out their index and link to their articles.

The theme/article.html file is parsed as a Go template. Syntax highlighting is generated at build time (no client-side JavaScript highlighting). theme/article.html accepts a data structure like this:

{
  Article: {
    ID:            "example-article",
    Title:         "Example Article",
    LastUpdatedOn: "April 15, 2018",
    Body:          "<p>Hello, world.</p>",
  }
}

Deploy

Create a static site on Cloudflare Pages:

• Repository: https://github.com/croaky/blog
• Production branch: main
• Build command: git fetch --unshallow && go run main.go build
• Build output directory: public

To deploy the site, commit and push to the GitHub repo.

View deploy logs in the Cloudflare web interface.