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
|
# cleberg.net
This repository holds the files for [cleberg.net](https://cleberg.net),
a static-site with blog posts, personal links, and more.
This site uses [weblorg](https://github.com/emacs-love/weblorg) to build
the static site, which relies on
[emacs](https://www.gnu.org/software/emacs/).
## Site Structure
I write content pages (e.g., blog posts) in org-mode and templates in
HTML. I use Weblorg to build these files into a static site, and then
deploy them to a web server.
The main site components are:
- Org source files containing content, including blog posts and pages.
- A configuration file (`publish.el`) that specifies publishing
parameters like base URL, output directories, and export options.
- Assets such as images and style sheets, located in designated
subdirectories.
- Utility scripts (e.g., `build.py`) to facilitate building and
deployment.
## Dependencies
The publishing system depends on:
- Emacs text editor with Org-Mode.
- The weblorg package, available at
[emacs-love/weblorg](https://github.com/emacs-love/weblorg), which
provides advanced Org publishing functionality and theming support.
## Configuration
You can customize site settings can within the `publish.el` file. This
file establishes key variables such as:
- The base URL for links.
- Output directories.
- Publishing rules to define which files to convert and how.
- Theme settings managed by weblorg.
Users intending to modify site parameters should review and edit this
file accordingly. The weblorg documentation contains extensive details
on configuration options and expected formats.
## Setup Instructions
To obtain a working copy of this repository, execute the following
commands within a shell environment or Emacs shell interface:
``` shell
git clone https://git.sr.ht/~ccleberg/cleberg.net
cd cleberg.net
emacs -nw
```
For users employing Doom Emacs, open any repository Org file using
`SPC f f` to access the content.
## Building and Publishing the Site
The publishing process involves invoking Emacs with the `publish.el`
script, which performs the export of Org documents to HTML output.
Configure the environment variable `ENV` as follows:
- If you set `ENV` to `prod`, the script uses production base URL
settings as defined in `publish.el`.
- If you do not set `ENV` or set it differently, the script defaults to
development settings, typically using `localhost:8000` as the base
URL.
Example commands to build the site:
``` shell
# Production build:
ENV=prod emacs --script publish.el
# Development build:
emacs --script publish.el
```
Generated site files reside in the designated output directory, ready
for deployment. You can deploy the resulting static site files via
standard file transfer protocols such as `scp` or SFTP.
The `build.py` script automates the build process. You can execute this
script with or without the `ENV` variable to perform production or
development builds respectively.
``` shell
# Production build script:
ENV=prod uv run build.py
# Development build script:
uv run build.py
```
## Deployment
Production builds emit root-relative URLs (`/styles.min.css`,
`/img/blog/...`) instead of absolute `https://` ones so the site renders
standalone on the onion service without fetching assets off-onion.
This means the web server must serve the image store at `/img/` on the
`cleberg.net` vhost. The images live at `/var/www/img/` (their own host,
`img.cleberg.net`); expose them under `cleberg.net/img/` with a symlink:
``` shell
ln -s /var/www/img /var/www/cleberg.net/img
```
Without this, images 404 in production. Development builds keep the
absolute `img.cleberg.net` URLs, so local previews load images from the
live host and need no symlink.
Once assets are same-origin, the vhost CSP can tighten `img-src`,
`style-src`, and `font-src` back to `'self'`. After deploying, purge the
Cloudflare cache (responses carry a 31-day `max-age`).
## Creating New Blog Posts
To add new blog content, follow this procedure within Emacs:
1. Open a new Org file (via `C-x C-f` or Doom\'s `SPC f f`).
2. Insert the contents of the post template with `C-x i`, sourcing from
`utils/template.org`.
3. Modify the new file as needed to add post content and metadata.
This method streamlines content creation by reusing a preformatted
template.
|
