convert README to md

1 files changed, 112 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..9bbb033
--- /dev/null
+++ b/README.md
@@ -0,0 +1,112 @@
+# cleberg.net
+
+This repository holds the files for [cleberg.net](https://cleberg.net),
+a static-site with blog posts, personal links, and more.
+
+This site uses [weblorg](https://github.com/emacs-love/weblorg) to build
+the static site, which relies on
+[emacs](https://www.gnu.org/software/emacs/).
+
+## Site Structure
+
+I write content pages (e.g., blog posts) in org-mode and templates in
+HTML. I use Weblorg to build these files into a static site, and then
+deploy them 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 style sheets, located in designated
+  subdirectories.
+- Utility scripts (e.g., `build.py`) to facilitate building and
+  deployment.
+
+## Dependencies
+
+The publishing system depends on:
+
+- Emacs text editor with Org-Mode.
+- The weblorg package, available at
+  [emacs-love/weblorg](https://github.com/emacs-love/weblorg), which
+  provides advanced Org publishing functionality and theming support.
+
+## Configuration
+
+You can customize site settings can within the `publish.el` file. This
+file establishes key variables such as:
+
+- The base URL for links.
+- Output directories.
+- Publishing rules to define which files to convert and how.
+- Theme settings managed by weblorg.
+
+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.
+
+## Setup Instructions
+
+To obtain a working copy of this repository, execute the following
+commands within a shell environment or Emacs shell interface:
+
+``` shell
+git clone https://github.com/ccleberg/cleberg.net
+cd cleberg.net
+emacs -nw
+```
+
+For users employing Doom Emacs, open any repository Org file using
+`SPC f f` to access the content.
+
+## Building and Publishing the Site
+
+The publishing process involves invoking Emacs with the `publish.el`
+script, which performs the export of Org documents to HTML output.
+
+Configure the environment variable `ENV` as follows:
+
+- If you set `ENV` to `prod`, the script uses production base URL
+  settings as defined in `publish.el`.
+- If you do not set `ENV` or set it differently, the script defaults to
+  development settings, typically using `localhost:8000` as the base
+  URL.
+
+Example commands to build the site:
+
+``` shell
+# Production build:
+ENV=prod emacs --script publish.el
+
+# Development build:
+emacs --script publish.el
+```
+
+Generated site files reside in the designated output directory, ready
+for deployment. You can deploy the resulting static site files via
+standard file transfer protocols such as `scp` or SFTP.
+
+The `build.py` script automates the build process. You can execute this
+script with or without the `ENV` variable to perform production or
+development builds respectively.
+
+``` shell
+# Production build script:
+ENV=prod uv run build.py
+
+# Development build script:
+uv run build.py
+```
+
+## Creating New Blog Posts
+
+To add new blog content, follow this procedure within Emacs:
+
+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.
+
+This method streamlines content creation by reusing a preformatted
+template.