Commit `68d43ac923`

68d43ac9231a8c50094972b414e09e4663061ca5

parent: 703ab9eb9c

Unsigned

cmc <hello@cleberg.net> · 2025-08-01 03:13 UTC

fix: format readme

Layout: unified · split

README.md +43 −95

		@@ -1,19 +1,3 @@
1
2		# Table of Contents
3
4		1. [cleberg.net](#org7e6a5fc)
5		1. [Site Structure](#orgdb622a7)
6		2. [Dependencies](#org4029d4c)
7		3. [Viewing the Site Examples](#orgd805aba)
8		4. [Configuration](#orgc1b1a3d)
9		5. [Setup Instructions](#org16caf48)
10		6. [Building and Publishing the Site](#org507540e)
11		7. [Creating New Blog Posts](#org99866ce)
12		8. [Contributing and Issue Tracking](#org57a6a9c)
13
14
15		<a id="org7e6a5fc"></a>
16
17	1	# cleberg.net
18	2
19	3	This document describes the structure and usage of the `cleberg.net` project.
		@@ -21,9 +5,6 @@ The site is built and maintained using the Org-Mode publishing system within
21	5	Emacs, supported by the weblorg package. This setup allows for generation of
22	6	static HTML content from Org files using a declarative configuration.
23	7
24
25		<a id="orgdb622a7"></a>
26
27	8	## Site Structure
28	9
29	10	The project source files are written in Org-Mode format and reside in the
		@@ -32,88 +13,57 @@ output, which can then be deployed to a web server.
32	13
33	14	The main site components are:
34	15
35		- Org source files containing content, including blog posts and pages.
36		- A configuration file (`publish.el`) that specifies publishing parameters like
37		base URL, output directories, and export options.
38		- Assets such as images and stylesheets, located in designated subdirectories.
39		- Utility scripts (e.g., `build.sh`) to facilitate building and deployment.
40
41
42		<a id="org4029d4c"></a>
	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 stylesheets, located in designated subdirectories.
	20	- Utility scripts (e.g., `build.sh`) to facilitate building and deployment.
43	21
44	22	## Dependencies
45	23
46	24	The publishing system depends on:
47	25
48		- Emacs text editor with Org-Mode.
49		- The weblorg package, available at <https://github.com/emacs-love/weblorg>, which
50		provides advanced Org publishing functionality and theming support.
51
52
53		<a id="orgd805aba"></a>
	26	- Emacs text editor with Org-Mode.
	27	- The weblorg package, available at <https://github.com/emacs-love/weblorg>, which
	28	provides advanced Org publishing functionality and theming support.
54	29
55	30	## Viewing the Site Examples
56	31
57	32	Screenshots illustrating the site in both light and dark display modes are
58	33	included in the `./screenshots/` directory.
59	34
60		<table border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
61
62
63		<colgroup>
64		<col class="org-left" />
65
66		<col class="org-left" />
67		</colgroup>
68		<thead>
69		<tr>
70		<th scope="col" class="org-left">Light Mode</th>
71		<th scope="col" class="org-left">Dark Mode</th>
72		</tr>
73		</thead>
74		<tbody>
75		<tr>
76		<td class="org-left"><img src="./screenshots/light.png" alt="light.png" /></td>
77		<td class="org-left"><img src="./screenshots/dark.png" alt="dark.png" /></td>
78		</tr>
79		</tbody>
80		</table>
81
82
83		<a id="orgc1b1a3d"></a>
	35	\| Light Mode \| Dark Mode \|
	36	\| ---------------------------- \| --------------------------- \|
	37	\| ![](./screenshots/light.png) \| ![](./screenshots/dark.png) \|
84	38
85	39	## Configuration
86	40
87	41	Custom site settings are centralized in the `publish.el` file. This file
88	42	establishes key variables such as:
89	43
90		- The base URL for links.
91		- Output directories.
92		- Publishing rules defining which files are converted and how.
93		- Theme settings managed by weblorg.
	44	- The base URL for links.
	45	- Output directories.
	46	- Publishing rules defining which files are converted and how.
	47	- Theme settings managed by weblorg.
94	48
95	49	Users intending to modify site parameters should review and edit this file
96	50	accordingly. The weblorg documentation contains extensive details on
97	51	configuration options and expected formats.
98	52
99
100		<a id="org16caf48"></a>
101
102	53	## Setup Instructions
103	54
104	55	To obtain a working copy of this repository, execute the following commands
105	56	within a shell environment or Emacs’ shell interface:
106	57
107		git clone https://git.sr.ht/~cxc/cleberg.net
108		cd cleberg.net
109		emacs -nw
	58	```shell
	59	git clone https://git.sr.ht/~cxc/cleberg.net
	60	cd cleberg.net
	61	emacs -nw
	62	```
110	63
111	64	For users employing Doom Emacs, open any repository Org file using `SPC f f` to
112	65	access the content.
113	66
114
115		<a id="org507540e"></a>
116
117	67	## Building and Publishing the Site
118	68
119	69	The publishing process involves invoking Emacs with the `publish.el` script,
		@@ -121,18 +71,20 @@ which performs the export of Org documents to HTML output.
121	71
122	72	Configure the environment variable `ENV` as follows:
123	73
124		- If `ENV` is set to `prod`, the script uses production base URL settings as
125		defined in `publish.el`.
126		- If `ENV` is unset or set differently, the script defaults to development
127		settings, typically using `localhost:8000` as the base URL.
	74	- If `ENV` is set to `prod`, the script uses production base URL settings as
	75	defined in `publish.el`.
	76	- If `ENV` is unset or set differently, the script defaults to development
	77	settings, typically using `localhost:8000` as the base URL.
128	78
129	79	Example commands to build the site:
130	80
131		# Production build:
132		ENV=prod emacs --script publish.el
133
134		# Development build:
135		emacs --script publish.el
	81	```shell
	82	# Production build:
	83	ENV=prod emacs --script publish.el
	84
	85	# Development build:
	86	emacs --script publish.el
	87	```
136	88
137	89	Generated site files reside in the designated output directory, ready for
138	90	deployment. Deployment can be performed by standard file transfer protocols such
		@@ -142,35 +94,31 @@ The `./build.sh` script automates the build process. It can be executed with or
142	94	without the `ENV` variable to perform production or development builds
143	95	respectively.
144	96
145		# Production build script:
146		ENV=prod ./build.sh
147
148		# Development build script:
149		./build.sh
150
151
152		<a id="org99866ce"></a>
	97	```shell
	98	# Production build script:
	99	ENV=prod ./build.sh
	100
	101	# Development build script:
	102	./build.sh
	103	```
153	104
154	105	## Creating New Blog Posts
155	106
156	107	To add new blog content, follow this procedure within Emacs:
157	108
158		1. Open a new Org file (via `C-x C-f` or Doom’s `SPC f f`).
159		2. Insert the contents of the post template with `C-x i`, sourcing from
160		`utils/template.org`.
161		3. Modify the new file as needed to add post content and metadata.
	109	1. Open a new Org file (via `C-x C-f` or Doom's `SPC f f`).
	110	2. Insert the contents of the post template with `C-x i`, sourcing from
	111	`utils/template.org`.
	112	3. Modify the new file as needed to add post content and metadata.
162	113
163	114	This method streamlines content creation by reusing a preformatted template.
164	115
165	116
166		<a id="org57a6a9c"></a>
167
168	117	## Contributing and Issue Tracking
169	118
170		Contributions and bug reports are tracked through the repository’s issue tab on
	119	Contributions and bug reports are tracked through the repository's issue tab on
171	120	GitHub. Users are encouraged to submit reports, feature requests, or pull
172	121	requests following standard repository guidelines.
173	122
174	123	For further details on the usage of Org-Mode, weblorg configuration, or
175	124	publishing workflows, consult the respective documentation sources.
176

README.org deleted −123

		@@ -1,123 +0,0 @@
1		* cleberg.net
2
3		This document describes the structure and usage of the =cleberg.net= project.
4		The site is built and maintained using the Org-Mode publishing system within
5		Emacs, supported by the weblorg package. This setup allows for generation of
6		static HTML content from Org files using a declarative configuration.
7
8		** Site Structure
9
10		The project source files are written in Org-Mode format and reside in the
11		repository. These files are processed by the publishing engine to produce HTML
12		output, which can then be deployed to a 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 stylesheets, located in designated subdirectories.
20		- Utility scripts (e.g., =build.sh=) 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, which
28		provides advanced Org publishing functionality and theming support.
29
30		** Viewing the Site Examples
31
32		Screenshots illustrating the site in both light and dark display modes are
33		included in the =./screenshots/= directory.
34
35		\| Light Mode \| Dark Mode \|
36		\|-------------------------+------------------------\|
37		\| [[./screenshots/light.png]] \| [[./screenshots/dark.png]] \|
38
39		** Configuration
40
41		Custom site settings are centralized in the =publish.el= file. This file
42		establishes key variables such as:
43
44		- The base URL for links.
45		- Output directories.
46		- Publishing rules defining which files are converted and how.
47		- Theme settings managed by weblorg.
48
49		Users intending to modify site parameters should review and edit this file
50		accordingly. The weblorg documentation contains extensive details on
51		configuration options and expected formats.
52
53		** Setup Instructions
54
55		To obtain a working copy of this repository, execute the following commands
56		within a shell environment or Emacs' shell interface:
57
58		#+begin_src shell
59		git clone https://git.sr.ht/~cxc/cleberg.net
60		cd cleberg.net
61		emacs -nw
62		#+end_src
63
64		For users employing Doom Emacs, open any repository Org file using =SPC f f= to
65		access the content.
66
67		** Building and Publishing the Site
68
69		The publishing process involves invoking Emacs with the =publish.el= script,
70		which performs the export of Org documents to HTML output.
71
72		Configure the environment variable =ENV= as follows:
73
74		- If =ENV= is set to =prod=, the script uses production base URL settings as
75		defined in =publish.el=.
76		- If =ENV= is unset or set differently, the script defaults to development
77		settings, typically using =localhost:8000= as the base URL.
78
79		Example commands to build the site:
80
81		#+begin_src shell
82		# Production build:
83		ENV=prod emacs --script publish.el
84
85		# Development build:
86		emacs --script publish.el
87		#+end_src
88
89		Generated site files reside in the designated output directory, ready for
90		deployment. Deployment can be performed by standard file transfer protocols such
91		as =scp= or SFTP.
92
93		The =./build.sh= script automates the build process. It can be executed with or
94		without the =ENV= variable to perform production or development builds
95		respectively.
96
97		#+begin_src shell
98		# Production build script:
99		ENV=prod ./build.sh
100
101		# Development build script:
102		./build.sh
103		#+end_src
104
105		** Creating New Blog Posts
106
107		To add new blog content, follow this procedure within Emacs:
108
109		1. Open a new Org file (via =C-x C-f= or Doom's =SPC f f=).
110		2. Insert the contents of the post template with =C-x i=, sourcing from
111		=utils/template.org=.
112		3. Modify the new file as needed to add post content and metadata.
113
114		This method streamlines content creation by reusing a preformatted template.
115
116		** Contributing and Issue Tracking
117
118		Contributions and bug reports are tracked through the repository's issue tab on
119		GitHub. Users are encouraged to submit reports, feature requests, or pull
120		requests following standard repository guidelines.
121
122		For further details on the usage of Org-Mode, weblorg configuration, or
123		publishing workflows, consult the respective documentation sources.

Commit 68d43ac923

Commit `68d43ac923`