blog

Short articles about software at https://dancroak.com. Static site generator designed to be deployed to Netlify.

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
│   │   └── _headers
│   ├── article.html
│   └── index.html
└── config.json

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:

Instantiate a client:

```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.

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

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

Configure articles in config.json:

[
  {
    "description": "Draft scheduled for future date.",
    "id": "article-draft-scheduled",
    "last_updated": "2050-01-01",
    "published": "2050-01-01",
    "tags": [
      "go",
      "react"
    ]
  },
  {
    "description": "Redirect old URL slugs.",
    "id": "article-with-redirects",
    "last_updated": "2018-02-01",
    "published": "2018-02-01",
    "tags": [
      "go"
    ]
    "redirects": [
      "/article-original-name",
      "/article-renamed-again",
      "/this-feature-works-only-on-netlify",
    ]
  },
  {
    "canonical": "https://seo.example.com/avoid-duplicate-content-penalty",
    "description": "Canonical article is on a separate site.",
    "id": "article-with-rel-canonical",
    "last_updated": "2018-01-15",
    "published": "2018-01-15",
    "tags": [
      "go"
    ]
  }
]

The description is used for the article page's meta description.

The id must match a Markdown file articles/id.md. It is also used for the article's URL slug.

The last_updated date can be in the future. A GitHub Action is scheduled daily to auto-publish to Netlify.

The redirects are converted into a Netlify _redirects file.

Modify theme

All theme/public files are copied to public. theme/public/_headers are Netlify Headers.

The theme/*.html files are parsed as Go templates. The theme/article.html template accepts a data structure like this:

{
  Article: {
    Body:          "<p>Hello, world.</p>",
    Canonical:     "https://seo.example.com/avoid-duplicate-content-penalty"
    Description:   "Hello, world.",
    ID:            "example-article",
    LastUpdatedOn: "April 15, 2018",
    Tags:          ["go", "unix"],
    Title:         "Example Article",
  }
}

The theme/index.html template accepts a data structure like this:

{
  Articles: [
    {
      Body:          "<p>Hello, world.</p>",
      Description:   "Hello, world.",
      ID:            "example-article",
      LastUpdatedIn: "2018 April",
      Tags:          ["go", "unix"],
      Title:         "Example Article",
    }
  ],
  Tags: ["go", "unix"],
}

Publish

Configure Netlify:

• Repository: https://github.com/croaky/blog
• Production branch: main
• Build command: go run main.go build
• Public folder: public

To publish articles, commit and push to the GitHub repo.

View deploy logs in the Netlify web interface.