50439e09ca · cmc/cleberg.net

1

* cleberg.net

1

* cleberg.net

2

3

[[https://cleberg.net][cleberg.net]] is my personal web page and blog. This website and blog utilize the

3

This document describes the structure and usage of the =cleberg.net= project.

4

powerful Org-Mode publishing system, courtesy of the [[https://github.com/emacs-love/weblorg][weblorg]] Emacs package.

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

| Light Mode | Dark Mode |

35

| Light Mode | Dark Mode |

7

|-------------------------+------------------------|

36

|-------------------------+------------------------|

8

| [[./screenshots/light.png]] | [[./screenshots/dark.png]] |

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

49

Users intending to modify site parameters should review and edit this file

13

through a simple =publish.el= file. For those who are interested in tweaking the

50

accordingly. The weblorg documentation contains extensive details on

14

underlying configuration, the weblorg documentation provides all necessary

51

configuration options and expected formats.

15

details on possible settings and options.

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

55

To obtain a working copy of this repository, execute the following commands

20

a local copy of the repository. This can be accomplished by running the

56

within a shell environment or Emacs’ shell interface:

21

following commands within Emacs:

22

57

23

#+begin_src shell

58

#+begin_src shell

24

git clone https://github.com/ccleberg/cleberg.net && \

59

git clone https://github.com/ccleberg/cleberg.net

25

cd cleberg.net && \

60

cd cleberg.net

26

emacs -nw

61

emacs -nw

27

#+end_src

62

#+end_src

28

63

29

Alternatively, if you prefer working with Doom, simply open any of the

64

For users employing Doom Emacs, open any repository Org file using =SPC f f= to

30

repository files using =Spc f f= and selecting =README.org=. From there, feel

65

access the content.

31

free to make any necessary changes or customizations.

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.

72

Configure the environment variable =ENV= as follows:

38

If ENV is omitted, it will default to =localhost:8000=. If =ENV=prod=, weblorg

73

39

will look in the =publish.el= file for the production 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.

78

79

Example commands to build the site:

40

80

41

#+begin_src shell

81

#+begin_src shell

42

# production:

82

# Production build:

43

ENV=prod emacs --script publish.el

83

ENV=prod emacs --script publish.el

44

84

45

# development:

85

# Development build:

46

emacs --script publish.el

86

emacs --script publish.el

47

#+end_src

87

#+end_src

48

88

49

The resulting files can then be deployed to your desired target using any method

89

Generated site files reside in the designated output directory, ready for

50

of your choice, such as =scp= or SFTP.

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

93

The =./build.sh= script automates the build process. It can be executed with or

53

automate this process. To do so, simply customize and run the script as needed.

94

without the =ENV= variable to perform production or development builds

95

respectively.

54

96

55

#+begin_src shell

97

#+begin_src shell

56

# production:

98

# Production build script:

57

ENV=prod ./build.sh

99

ENV=prod ./build.sh

58

100

59

# development:

101

# Development build script:

60

./build.sh

102

./build.sh

61

#+end_src

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.

114

This method streamlines content creation by reusing a preformatted template.

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.

71

115

72

This streamlined process allows you to rapidly generate fresh content for

116

** Contributing and Issue Tracking

73

cleberg.net, taking advantage of the existing template structure and formatting.

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

122

For further details on the usage of Org-Mode, weblorg configuration, or

78

outstanding issues, please refer to the issues tab. This is where you can find a

123

publishing workflows, consult the respective documentation sources.

79

comprehensive list of open tickets or submit a new ticket for consideration.

	@@ -1,79 +1,123 @@
1	* cleberg.net	1	* cleberg.net
2		2
3	[[https://cleberg.net][cleberg.net]] is my personal web page and blog. This website and blog utilize the	3	This document describes the structure and usage of the =cleberg.net= project.
4	powerful Org-Mode publishing system, courtesy of the [[https://github.com/emacs-love/weblorg][weblorg]] Emacs package.	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	\| Light Mode \| Dark Mode \|	35	\| Light Mode \| Dark Mode \|
7	\|-------------------------+------------------------\|	36	\|-------------------------+------------------------\|
8	\| [[./screenshots/light.png]] \| [[./screenshots/dark.png]] \|	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	49	Users intending to modify site parameters should review and edit this file
13	through a simple =publish.el= file. For those who are interested in tweaking the	50	accordingly. The weblorg documentation contains extensive details on
14	underlying configuration, the weblorg documentation provides all necessary	51	configuration options and expected formats.
15	details on possible settings and options.
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	55	To obtain a working copy of this repository, execute the following commands
20	a local copy of the repository. This can be accomplished by running the	56	within a shell environment or Emacs’ shell interface:
21	following commands within Emacs:
22		57
23	#+begin_src shell	58	#+begin_src shell
24	git clone https://github.com/ccleberg/cleberg.net && \	59	git clone https://github.com/ccleberg/cleberg.net
25	cd cleberg.net && \	60	cd cleberg.net
26	emacs -nw	61	emacs -nw
27	#+end_src	62	#+end_src
28		63
29	Alternatively, if you prefer working with Doom, simply open any of the	64	For users employing Doom Emacs, open any repository Org file using =SPC f f= to
30	repository files using =Spc f f= and selecting =README.org=. From there, feel	65	access the content.
31	free to make any necessary changes or customizations.
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.	72	Configure the environment variable =ENV= as follows:
38	If ENV is omitted, it will default to =localhost:8000=. If =ENV=prod=, weblorg	73
39	will look in the =publish.el= file for the production 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.
		78
		79	Example commands to build the site:
40		80
41	#+begin_src shell	81	#+begin_src shell
42	# production:	82	# Production build:
43	ENV=prod emacs --script publish.el	83	ENV=prod emacs --script publish.el
44		84
45	# development:	85	# Development build:
46	emacs --script publish.el	86	emacs --script publish.el
47	#+end_src	87	#+end_src
48		88
49	The resulting files can then be deployed to your desired target using any method	89	Generated site files reside in the designated output directory, ready for
50	of your choice, such as =scp= or SFTP.	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	93	The =./build.sh= script automates the build process. It can be executed with or
53	automate this process. To do so, simply customize and run the script as needed.	94	without the =ENV= variable to perform production or development builds
		95	respectively.
54		96
55	#+begin_src shell	97	#+begin_src shell
56	# production:	98	# Production build script:
57	ENV=prod ./build.sh	99	ENV=prod ./build.sh
58		100
59	# development:	101	# Development build script:
60	./build.sh	102	./build.sh
61	#+end_src	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.	114	This method streamlines content creation by reusing a preformatted template.
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.
71		115
72	This streamlined process allows you to rapidly generate fresh content for	116	** Contributing and Issue Tracking
73	cleberg.net, taking advantage of the existing template structure and formatting.
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	122	For further details on the usage of Org-Mode, weblorg configuration, or
78	outstanding issues, please refer to the issues tab. This is where you can find a	123	publishing workflows, consult the respective documentation sources.
79	comprehensive list of open tickets or submit a new ticket for consideration.

Commit 50439e09ca

Commit `50439e09ca`