README.org

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