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