fix(README): update entire README

1 files changed, 85 insertions, 41 deletions

diff --git a/README.org b/README.org
index 16f4a2b..3d222bd 100644
--- a/README.org
+++ b/README.org
@@ -1,79 +1,123 @@
 * cleberg.net
 
-[[https://cleberg.net][cleberg.net]] is my personal web page and blog. This website and blog utilize the
-powerful Org-Mode publishing system, courtesy of the [[https://github.com/emacs-love/weblorg][weblorg]] Emacs package.
+This document describes the structure and usage of the =cleberg.net= project.
+The site is built and maintained using the Org-Mode publishing system within
+Emacs, supported by the weblorg package. This setup allows for generation of
+static HTML content from Org files using a declarative configuration.
+
+** Site Structure
+
+The project source files are written in Org-Mode format and reside in the
+repository. These files are processed by the publishing engine to produce HTML
+output, which can then be deployed to a web server.
+
+The main site components are:
+
+- Org source files containing content, including blog posts and pages.
+- A configuration file (=publish.el=) that specifies publishing parameters like
+  base URL, output directories, and export options.
+- Assets such as images and stylesheets, located in designated subdirectories.
+- Utility scripts (e.g., =build.sh=) to facilitate building and deployment.
+
+** Dependencies
+
+The publishing system depends on:
+
+- Emacs text editor with Org-Mode.
+- The weblorg package, available at https://github.com/emacs-love/weblorg, which
+  provides advanced Org publishing functionality and theming support.
+
+** Viewing the Site Examples
+
+Screenshots illustrating the site in both light and dark display modes are
+included in the =./screenshots/= directory.
 
 | Light Mode              | Dark Mode              |
 |-------------------------+------------------------|
 | [[./screenshots/light.png]] | [[./screenshots/dark.png]] |
 
-** Features & Configuration
+** Configuration
+
+Custom site settings are centralized in the =publish.el= file. This file
+establishes key variables such as:
+
+- The base URL for links.
+- Output directories.
+- Publishing rules defining which files are converted and how.
+- Theme settings managed by weblorg.
 
-This site leverages the flexibility of Org-Mode to allow for easy customization
-through a simple =publish.el= file. For those who are interested in tweaking the
-underlying configuration, the weblorg documentation provides all necessary
-details on possible settings and options.
+Users intending to modify site parameters should review and edit this file
+accordingly. The weblorg documentation contains extensive details on
+configuration options and expected formats.
 
-** Getting Started
+** Setup Instructions
 
-To begin exploring or contributing to this project, you'll first need to set up
-a local copy of the repository. This can be accomplished by running the
-following commands within Emacs:
+To obtain a working copy of this repository, execute the following commands
+within a shell environment or Emacs’ shell interface:
 
 #+begin_src shell
-git clone https://github.com/ccleberg/cleberg.net && \
-cd cleberg.net && \
+git clone https://github.com/ccleberg/cleberg.net
+cd cleberg.net
 emacs -nw
 #+end_src
 
-Alternatively, if you prefer working with Doom, simply open any of the
-repository files using =Spc f f= and selecting =README.org=. From there, feel
-free to make any necessary changes or customizations.
+For users employing Doom Emacs, open any repository Org file using =SPC f f= to
+access the content.
 
-** Building & Publishing the Site
+** Building and Publishing the Site
 
-To test the site locally within Emacs, run the following command sequence:
+The publishing process involves invoking Emacs with the =publish.el= script,
+which performs the export of Org documents to HTML output.
 
-Use the =ENV= environment variable to determine which base URL weblorg will use.
-If ENV is omitted, it will default to =localhost:8000=. If =ENV=prod=, weblorg
-will look in the =publish.el= file for the production base URL.
+Configure the environment variable =ENV= as follows:
+
+- If =ENV= is set to =prod=, the script uses production base URL settings as
+  defined in =publish.el=.
+- If =ENV= is unset or set differently, the script defaults to development
+  settings, typically using =localhost:8000= as the base URL.
+
+Example commands to build the site:
 
 #+begin_src shell
-# production:
+# Production build:
 ENV=prod emacs --script publish.el
 
-# development:
+# Development build:
 emacs --script publish.el
 #+end_src
 
-The resulting files can then be deployed to your desired target using any method
-of your choice, such as =scp= or SFTP.
+Generated site files reside in the designated output directory, ready for
+deployment. Deployment can be performed by standard file transfer protocols such
+as =scp= or SFTP.
 
-Alternatively, you may prefer to utilize the provided =build.sh= script to
-automate this process. To do so, simply customize and run the script as needed.
+The =./build.sh= script automates the build process. It can be executed with or
+without the =ENV= variable to perform production or development builds
+respectively.
 
 #+begin_src shell
-# production:
+# Production build script:
 ENV=prod ./build.sh
 
-# development:
+# Development build script:
 ./build.sh
 #+end_src
 
-*** Creating New Blog Posts
+** Creating New Blog Posts
+
+To add new blog content, follow this procedure within Emacs:
 
-To quickly create a new blog post within Emacs, follow these steps:
+1. Open a new Org file (via =C-x C-f= or Doom's =SPC f f=).
+2. Insert the contents of the post template with =C-x i=, sourcing from
+   =utils/template.org=.
+3. Modify the new file as needed to add post content and metadata.
 
-1. Run =C-x C-f= (=SPC f f= in Doom) to open a new Org-Mode file.
-2. Utilize the =insert-file-contents= command by pressing =C-x i=.
-3. Direct the contents of =template.org= (located at =utils/template.org=) into
-   the newly opened file.
+This method streamlines content creation by reusing a preformatted template.
 
-This streamlined process allows you to rapidly generate fresh content for
-cleberg.net, taking advantage of the existing template structure and formatting.
+** Contributing and Issue Tracking
 
-** Contributing & Tasks
+Contributions and bug reports are tracked through the repository’s issue tab on
+GitHub. Users are encouraged to submit reports, feature requests, or pull
+requests following standard repository guidelines.
 
-For those interested in contributing to this project or addressing any
-outstanding issues, please refer to the issues tab. This is where you can find a
-comprehensive list of open tickets or submit a new ticket for consideration.
+For further details on the usage of Org-Mode, weblorg configuration, or
+publishing workflows, consult the respective documentation sources.