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