diff options
| -rw-r--r-- | README.md | 112 | ||||
| -rw-r--r-- | README.org | 105 |
2 files changed, 112 insertions, 105 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. diff --git a/README.org b/README.org deleted file mode 100644 index 33bbf75..0000000 --- a/README.org +++ /dev/null @@ -1,105 +0,0 @@ -* 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][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: - -#+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. |