Commit `b3591bd8b0`

b3591bd8b04c6945d7ec51cb64cfc7ad3dc618d1

parent: f57acd569d

Verified · cmc

cmc <hello@cleberg.net> · 2026-03-16 03:51 UTC

convert README to md

Layout: unified · split

README.md added +112

		@@ -0,0 +1,112 @@
	1	# cleberg.net
	2
	3	This repository holds the files for [cleberg.net](https://cleberg.net),
	4	a static-site with blog posts, personal links, and more.
	5
	6	This site uses [weblorg](https://github.com/emacs-love/weblorg) to build
	7	the static site, which relies on
	8	[emacs](https://www.gnu.org/software/emacs/).
	9
	10	## Site Structure
	11
	12	I write content pages (e.g., blog posts) in org-mode and templates in
	13	HTML. I use Weblorg to build these files into a static site, and then
	14	deploy them to a web server.
	15
	16	The main site components are:
	17
	18	- Org source files containing content, including blog posts and pages.
	19	- A configuration file (`publish.el`) that specifies publishing
	20	parameters like base URL, output directories, and export options.
	21	- Assets such as images and style sheets, located in designated
	22	subdirectories.
	23	- Utility scripts (e.g., `build.py`) to facilitate building and
	24	deployment.
	25
	26	## Dependencies
	27
	28	The publishing system depends on:
	29
	30	- Emacs text editor with Org-Mode.
	31	- The weblorg package, available at
	32	[emacs-love/weblorg](https://github.com/emacs-love/weblorg), which
	33	provides advanced Org publishing functionality and theming support.
	34
	35	## Configuration
	36
	37	You can customize site settings can within the `publish.el` file. This
	38	file establishes key variables such as:
	39
	40	- The base URL for links.
	41	- Output directories.
	42	- Publishing rules to define which files to convert and how.
	43	- Theme settings managed by weblorg.
	44
	45	Users intending to modify site parameters should review and edit this
	46	file accordingly. The weblorg documentation contains extensive details
	47	on configuration options and expected formats.
	48
	49	## Setup Instructions
	50
	51	To obtain a working copy of this repository, execute the following
	52	commands within a shell environment or Emacs shell interface:
	53
	54	``` shell
	55	git clone https://github.com/ccleberg/cleberg.net
	56	cd cleberg.net
	57	emacs -nw
	58	```
	59
	60	For users employing Doom Emacs, open any repository Org file using
	61	`SPC f f` to access the content.
	62
	63	## Building and Publishing the Site
	64
	65	The publishing process involves invoking Emacs with the `publish.el`
	66	script, which performs the export of Org documents to HTML output.
	67
	68	Configure the environment variable `ENV` as follows:
	69
	70	- If you set `ENV` to `prod`, the script uses production base URL
	71	settings as defined in `publish.el`.
	72	- If you do not set `ENV` or set it differently, the script defaults to
	73	development settings, typically using `localhost:8000` as the base
	74	URL.
	75
	76	Example commands to build the site:
	77
	78	``` shell
	79	# Production build:
	80	ENV=prod emacs --script publish.el
	81
	82	# Development build:
	83	emacs --script publish.el
	84	```
	85
	86	Generated site files reside in the designated output directory, ready
	87	for deployment. You can deploy the resulting static site files via
	88	standard file transfer protocols such as `scp` or SFTP.
	89
	90	The `build.py` script automates the build process. You can execute this
	91	script with or without the `ENV` variable to perform production or
	92	development builds respectively.
	93
	94	``` shell
	95	# Production build script:
	96	ENV=prod uv run build.py
	97
	98	# Development build script:
	99	uv run build.py
	100	```
	101
	102	## Creating New Blog Posts
	103
	104	To add new blog content, follow this procedure within Emacs:
	105
	106	1. Open a new Org file (via `C-x C-f` or Doom\'s `SPC f f`).
	107	2. Insert the contents of the post template with `C-x i`, sourcing from
	108	`utils/template.org`.
	109	3. Modify the new file as needed to add post content and metadata.
	110
	111	This method streamlines content creation by reusing a preformatted
	112	template.

README.org deleted −105

		@@ -1,105 +0,0 @@
1		* cleberg.net
2
3		This repository holds the files for [[https://cleberg.net][cleberg.net]], a static-site with blog posts,
4		personal links, and more.
5
6		This site uses [[https://github.com/emacs-love/weblorg][weblorg]] to build the static site, which relies on [[https://www.gnu.org/software/emacs/][emacs]].
7
8		** Site Structure
9
10		I write content pages (e.g., blog posts) in org-mode and templates in HTML. I
11		use Weblorg to build these files into a static site, and then deploy them to a
12		web server.
13
14		The main site components are:
15
16		- Org source files containing content, including blog posts and pages.
17		- A configuration file (~publish.el~) that specifies publishing parameters like
18		base URL, output directories, and export options.
19		- Assets such as images and style sheets, located in designated subdirectories.
20		- Utility scripts (e.g., ~build.py~) to facilitate building and deployment.
21
22		** Dependencies
23
24		The publishing system depends on:
25
26		- Emacs text editor with Org-Mode.
27		- The weblorg package, available at [[https://github.com/emacs-love/weblorg][emacs-love/weblorg]], which provides advanced
28		Org publishing functionality and theming support.
29
30		** Configuration
31
32		You can customize site settings can within the ~publish.el~ file. This file
33		establishes key variables such as:
34
35		- The base URL for links.
36		- Output directories.
37		- Publishing rules to define which files to convert and how.
38		- Theme settings managed by weblorg.
39
40		Users intending to modify site parameters should review and edit this file
41		accordingly. The weblorg documentation contains extensive details on
42		configuration options and expected formats.
43
44		** Setup Instructions
45
46		To obtain a working copy of this repository, execute the following commands
47		within a shell environment or Emacs shell interface:
48
49		#+begin_src shell
50		git clone https://github.com/ccleberg/cleberg.net
51		cd cleberg.net
52		emacs -nw
53		#+end_src
54
55		For users employing Doom Emacs, open any repository Org file using ~SPC f f~ to
56		access the content.
57
58		** Building and Publishing the Site
59
60		The publishing process involves invoking Emacs with the ~publish.el~ script, which
61		performs the export of Org documents to HTML output.
62
63		Configure the environment variable ~ENV~ as follows:
64
65		- If you set ~ENV~ to ~prod~, the script uses production base URL settings as
66		defined in ~publish.el~.
67		- If you do not set ~ENV~ or set it differently, the script defaults to
68		development settings, typically using ~localhost:8000~ as the base URL.
69
70		Example commands to build the site:
71
72		#+begin_src shell
73		# Production build:
74		ENV=prod emacs --script publish.el
75
76		# Development build:
77		emacs --script publish.el
78		#+end_src
79
80		Generated site files reside in the designated output directory, ready for
81		deployment. You can deploy the resulting static site files via standard file
82		transfer protocols such as ~scp~ or SFTP.
83
84		The ~build.py~ script automates the build process. You can execute this script
85		with or without the ~ENV~ variable to perform production or development builds
86		respectively.
87
88		#+begin_src shell
89		# Production build script:
90		ENV=prod uv run build.py
91
92		# Development build script:
93		uv run build.py
94		#+end_src
95
96		** Creating New Blog Posts
97
98		To add new blog content, follow this procedure within Emacs:
99
100		1. Open a new Org file (via ~C-x C-f~ or Doom's ~SPC f f~).
101		2. Insert the contents of the post template with ~C-x i~, sourcing from
102		~utils/template.org~.
103		3. Modify the new file as needed to add post content and metadata.
104
105		This method streamlines content creation by reusing a preformatted template.

Commit b3591bd8b0

Commit `b3591bd8b0`