aboutsummaryrefslogtreecommitdiff
path: root/README.md
blob: a8758d57530c6db253a6bb109ac5e868cc7f64da (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
# pablotron.org

## Overview

[Hugo][] backend for [pablotron.org][].

Content is divided into three [sections][]:

|Section Type|Description|Permalinks|
|------------|-----------|---------|
|`posts`|Blog entries.|`/YYYY/MM/DD/SLUG/`|
|`articles`|Long-form articles.|`/articles/SLUG/`|
|`projects`|Programming projects.|`/SLUG/`|

The 10 most recent `posts` are shown on the home page blog in reverse
chronological order.  A list of all `posts`, grouped by year, is shown
on the [archive][] page in reverse chronological order.

`articles` are long-form content that doesn't fit nicely as blog posts.

`projects` have a repository link and a brief description.  Eventually I
may add more information (release history, signatures, etc).

## Usage

The `bin/new` script allows you (me) to quickly create new content by:

1. Expanding a section template ([Hugo][] calls these templates
   "archetypes") draft content.
2. Opening the draft content in your editor.

## Add Post

To add a new post:

    # easy version
    bin/new post some-blog-post

    # longer version
    hugo new --editor $EDITOR  posts/$(date +%Y-%m-%d)-some-blog-post.md

## Add Article

To add a new article:

    # easy version
    bin/new article some-article

    # longer version
    hugo new --editor $EDITOR  articles/some-article.md

## Add Project

To add a new project:

    # easy version
    bin/new project great-project

    # longer version
    hugo new --editor $EDITOR  projects/great-project.md

## Edit Navbar Menu

To add or edit navbar menu entries:

    # edit navbar menu entries
    vim data/menu.yaml

## Serve Locally

To serve this site locally:

    # serve hugo locally on port 1313
    hugo serve --minify --disableFastRender

**Notes:**
* `--minify` generates minified HTML, and
  [`html/template`][html-template] is aware of `<pre>` and `<code>` so
  inline code blocks work correctly.
* `--disableFastRenderer` may be unnecessary, but the fast
  renderer cache was giving me grief while doing theme development.

## Deploy Site

To deploy to production site:

*TODO*

# Theme

The current theme is `hugo-pt2021` and is stored in this repository as
`themes/hugo-pt2021`.

`hugo-pt2021` is depends on the following:

* [Bulma 0.9.3][bulma]: CSS framework.
* Several icons from [Feather Icons][feathericons].

The [Bulma][] [SASS][] is:

1. Stripped of extraneous styles.  See `assetes/style.sass`.
2. Combined with a small amount of `pt2021`-specific styling.  See
   `assets/style.sass`.
2. Converted from [SASS][] to [CSS][], minified, and fingerprinted
   using [Hugo Pipes][hugo-pipes].  See `layouts/partials/head.html`.
3. Written to `public/style.$HASH.css`.

[hugo]: https://gohugo.io/
  "hugo static site generator"
[sections]: https://gohugo.io/content-management/sections/
  "content sections"
[pablotron.org]: https://pablotron.org/
  "the hottest site on the net"
[archive]: https://pablotron.org/archive/
  "post archive"
[bulma]: https://bulma.io/
  "modern CSS framework"
[feathericons]: https://github.com/feathericons/feather
  "beautiful open source icons"
[hugo-pipes]: https://gohugo.io/hugo-pipes/
  "hugo asset processing pipeline"
[sass]: https://sass-lang.com/
  "Syntactically Awesome Style Sheets"
[css]: https://en.wikipedia.org/wiki/CSS
  "Cascading Style Sheets"
[go]: https://golang.org/
  "Go programming language"
[html-template]: https://pkg.go.dev/html/template
  "Go's built-in HTML template renderer"