From ad5864277d59e669093cded07142d90160482388 Mon Sep 17 00:00:00 2001 From: Christian Cleberg Date: Tue, 3 Feb 2026 17:56:52 -0600 Subject: convert README to org-mode --- README.md | 115 ------------------------------------------------------------- README.org | 114 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 114 insertions(+), 115 deletions(-) delete mode 100644 README.md create mode 100644 README.org diff --git a/README.md b/README.md deleted file mode 100644 index 081521b..0000000 --- a/README.md +++ /dev/null @@ -1,115 +0,0 @@ -# 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 - -Content pages (e.g., blog posts) are written in org-mode and templates are -written in HTML. Weblorg can be used to build these files into a static site, -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 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 , - which provides advanced Org publishing functionality and theming support. - -## Screenshots - -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) | - -## 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. - -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 `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: - -```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. Deployment can be performed by standard file transfer protocols such -as `scp` or SFTP. - -The `./build.py` script automates the build process. It can be executed 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. diff --git a/README.org b/README.org new file mode 100644 index 0000000..53a06c1 --- /dev/null +++ b/README.org @@ -0,0 +1,114 @@ +* cleberg.net + +This repository holds the files for [[https://cleberg.net][cleberg.net]], a static-site with blog posts, +personal links, and more. + +This site uses [[https://github.com/emacs-love/weblorg][weblorg]] to build the static site, which relies on [[https://www.gnu.org/software/emacs/][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 [[https://github.com/emacs-love/weblorg]], which + provides advanced Org publishing functionality and theming support. + +** Screenshots + +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]] | + +** 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: + +#+begin_src shell +git clone https://github.com/ccleberg/cleberg.net +cd cleberg.net +emacs -nw +#+end_src + +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: + +#+begin_src shell +# Production build: +ENV~prod emacs --script publish.el + +# Development build: +emacs --script publish.el +#+end_src + +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. + +#+begin_src shell +# Production build script: +ENV~prod uv run build.py + +# Development build script: +uv run build.py +#+end_src + +** 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. -- cgit v1.2.3