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
|
# cleberg.net
This document describes the structure and usage of the `cleberg.net` project.
The site is built and maintained using the Org-Mode publishing system within
Emacs, supported by the weblorg package. This setup allows for generation of
static HTML content from Org files using a declarative configuration.
## Site Structure
The project source files are written in Org-Mode format and reside in the
repository. These files are processed by the publishing engine to produce HTML
output, which can then be deployed 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 stylesheets, 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 <https://github.com/emacs-love/weblorg>, which
provides advanced Org publishing functionality and theming support.
## Viewing the Site Examples
Screenshots illustrating the site in both light and dark display modes are
included in the `./screenshots/` directory.
| Light Mode | Dark Mode |
| ---------------------------- | --------------------------- |
|  |  |
## Configuration
Custom site settings are centralized in the `publish.el` file. This file
establishes key variables such as:
- The base URL for links.
- Output directories.
- Publishing rules defining which files are converted 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/~cxc/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 `ENV` is set to `prod`, the script uses production base URL settings as
defined in `publish.el`.
- If `ENV` is unset or set 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. Deployment can be performed by standard file transfer protocols such
as `scp` or SFTP.
The `./build.py` script automates the build process. It can be executed 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
```
## 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.
## Contributing and Issue Tracking
Contributions and bug reports are tracked through the repository's issue tab on
GitHub. Users are encouraged to submit reports, feature requests, or pull
requests following standard repository guidelines.
For further details on the usage of Org-Mode, weblorg configuration, or
publishing workflows, consult the respective documentation sources.
|
