Commit `50439e09ca`

50439e09ca6741a2c55ba5a3089e76990b8ced68

parent: 373eff928d

Unsigned

cmc <hello@cleberg.net> · 2025-06-03 22:13 UTC

fix(README): update entire README

Layout: unified · split

README.org +85 −41

		@@ -1,79 +1,123 @@
1	1	* cleberg.net
2	2
3		[[https://cleberg.net][cleberg.net]] is my personal web page and blog. This website and blog utilize the
4		powerful Org-Mode publishing system, courtesy of the [[https://github.com/emacs-love/weblorg][weblorg]] Emacs package.
	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.
5	34
6	35	\| Light Mode \| Dark Mode \|
7	36	\|-------------------------+------------------------\|
8	37	\| [[./screenshots/light.png]] \| [[./screenshots/dark.png]] \|
9	38
10		** Features & Configuration
	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.
11	48
12		This site leverages the flexibility of Org-Mode to allow for easy customization
13		through a simple =publish.el= file. For those who are interested in tweaking the
14		underlying configuration, the weblorg documentation provides all necessary
15		details on possible settings and options.
	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.
16	52
17		** Getting Started
	53	** Setup Instructions
18	54
19		To begin exploring or contributing to this project, you'll first need to set up
20		a local copy of the repository. This can be accomplished by running the
21		following commands within Emacs:
	55	To obtain a working copy of this repository, execute the following commands
	56	within a shell environment or Emacs’ shell interface:
22	57
23	58	#+begin_src shell
24		git clone https://github.com/ccleberg/cleberg.net && \
25		cd cleberg.net && \
	59	git clone https://github.com/ccleberg/cleberg.net
	60	cd cleberg.net
26	61	emacs -nw
27	62	#+end_src
28	63
29		Alternatively, if you prefer working with Doom, simply open any of the
30		repository files using =Spc f f= and selecting =README.org=. From there, feel
31		free to make any necessary changes or customizations.
	64	For users employing Doom Emacs, open any repository Org file using =SPC f f= to
	65	access the content.
32	66
33		** Building & Publishing the Site
	67	** Building and Publishing the Site
34	68
35		To test the site locally within Emacs, run the following command sequence:
	69	The publishing process involves invoking Emacs with the =publish.el= script,
	70	which performs the export of Org documents to HTML output.
36	71
37		Use the =ENV= environment variable to determine which base URL weblorg will use.
38		If ENV is omitted, it will default to =localhost:8000=. If =ENV=prod=, weblorg
39		will look in the =publish.el= file for the production base URL.
	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:
40	80
41	81	#+begin_src shell
42		# production:
	82	# Production build:
43	83	ENV=prod emacs --script publish.el
44	84
45		# development:
	85	# Development build:
46	86	emacs --script publish.el
47	87	#+end_src
48	88
49		The resulting files can then be deployed to your desired target using any method
50		of your choice, such as =scp= or SFTP.
	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.
51	92
52		Alternatively, you may prefer to utilize the provided =build.sh= script to
53		automate this process. To do so, simply customize and run the script as needed.
	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.
54	96
55	97	#+begin_src shell
56		# production:
	98	# Production build script:
57	99	ENV=prod ./build.sh
58	100
59		# development:
	101	# Development build script:
60	102	./build.sh
61	103	#+end_src
62	104
63		*** Creating New Blog Posts
	105	** Creating New Blog Posts
	106
	107	To add new blog content, follow this procedure within Emacs:
64	108
65		To quickly create a new blog post within Emacs, follow these steps:
	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.
66	113
67		1. Run =C-x C-f= (=SPC f f= in Doom) to open a new Org-Mode file.
68		2. Utilize the =insert-file-contents= command by pressing =C-x i=.
69		3. Direct the contents of =template.org= (located at =utils/template.org=) into
70		the newly opened file.
	114	This method streamlines content creation by reusing a preformatted template.
71	115
72		This streamlined process allows you to rapidly generate fresh content for
73		cleberg.net, taking advantage of the existing template structure and formatting.
	116	** Contributing and Issue Tracking
74	117
75		** Contributing & Tasks
	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.
76	121
77		For those interested in contributing to this project or addressing any
78		outstanding issues, please refer to the issues tab. This is where you can find a
79		comprehensive list of open tickets or submit a new ticket for consideration.
	122	For further details on the usage of Org-Mode, weblorg configuration, or
	123	publishing workflows, consult the respective documentation sources.

Commit 50439e09ca

Commit `50439e09ca`