aboutsummaryrefslogtreecommitdiff
path: root/README.md
blob: 3e43060ea1a314348d88632cf561e86a12eef4eb (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
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
# 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 clone site repo:

```bash
# clone upstream repo (note wireguard hostname)
git clone k3.wg:/git/sites/pablotron.org.git
```

Then:

* make changes as usual
* commit changes
* push to upstream repo

The push will trigger a hook which runs
`/data/www/pablotron.org/data/bin/deploy.sh`, which will:

1. Pull the latest changes from the git repository
2. Run [Hugo][] to rebuild the site.
3. Update the `htdocs` symlink

# 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"