#+TITLE: AOG - Act of Genius
#+AUTHOR: Pankaj Doharey

* Overview

AOG (Act of Genius) is an Emacs Org-mode static site generator.  It is based
on the org-page lineage and is used here as an editor-first publishing engine
for technical blogs.

Core behavior:

1. Read Org source files from a repository.
2. Render content with Mustache templates and a selected theme.
3. Generate category pages, tag pages, and RSS/search artifacts.
4. Publish HTML output to a target directory or a configured branch workflow.


* Features

1. Org-native writing and export flow.
2. Theme system with template/CSS/JS resources.
3. Category and tag index generation.
4. RSS generation.
5. Incremental publication via git-aware workflows.
6. Search index generation support in downstream pipelines.
7. Highly scriptable Elisp integration.


* Dependencies

Required:

1. Emacs (batch mode).
2. Org-mode.
3. Git.
4. Elisp libraries used by AOG internals:
   =mustache.el=, =htmlize.el=, =dash.el=, =ht.el=, =git.el=.

Optional:

1. =simple-httpd= for Emacs-side preview flows.


* Installation

** Option 1: Load from local checkout

#+BEGIN_SRC emacs-lisp
(add-to-list 'load-path "/path/to/AOG")
(require 'aog)
#+END_SRC

** Option 2: Package-based installation

Install via your preferred Emacs package manager and then:

#+BEGIN_SRC emacs-lisp
(require 'aog)
#+END_SRC


* Minimal Configuration

#+BEGIN_SRC emacs-lisp
(setq aog/repository-directory "/path/to/blog-repo")
(setq aog/site-domain "https://example.com")
(setq aog/site-main-title "My Blog")
(setq aog/site-sub-title "Notes on systems and software")
(setq aog/theme 'selfdotsend) ; or any available theme
#+END_SRC

Optional identity and integrations:

#+BEGIN_SRC emacs-lisp
(setq aog/personal-github-link "https://github.com/your-user")
(setq aog/personal-disqus-shortname "your-disqus-id")
(setq aog/personal-google-analytics-id "G-XXXXXXX")
#+END_SRC


* Usage From Emacs

** Full publication

#+BEGIN_SRC emacs-lisp
(aog/do-publication)
#+END_SRC

** Publication to a target output directory

#+BEGIN_SRC emacs-lisp
(aog/do-publication t nil "/tmp/aog-public" nil nil)
#+END_SRC

** Interactive

Run:

#+BEGIN_EXAMPLE
M-x aog/do-publication
#+END_EXAMPLE


* CLI Workflow

AOG ships a terminal CLI at =bin/aog= so users can scaffold and publish without
cloning a pre-made site repository. A complete guide is in =docs/CLI.org=.

Install to PATH (example):

#+BEGIN_EXAMPLE
git clone git@github.com:metacritical/AOG.git
cd AOG
export PATH="$PWD/bin:$PATH"
#+END_EXAMPLE

Quick overview of commands:

#+BEGIN_EXAMPLE
aog create <site_name> [target_dir]   # scaffold a new site
aog publish [repo_dir] [output_dir]  # run AOG publication
aog preview [repo_dir] [output_dir] [port]  # publish and serve locally
aog new [repo_dir] [--publish] "Title"      # create a draft or post
aog ls [repo_dir]                    # list drafts
#+END_EXAMPLE

Rails-like quick start:

#+BEGIN_EXAMPLE
aog create "My New Site"
cd my-new-site
./publish.sh
python -m http.server 8080 -d public
#+END_EXAMPLE

See =docs/CLI.org= for details on site configuration, slug generation,
git-aware publishing, environment variables, and downstream repository scripts.


* Theme Development

Themes live under =themes/= and typically include:

1. =templates/= (Mustache templates)
2. =resources/css=
3. =resources/js=
4. optional images/fonts

For downstream blog repos, theme resources are copied into generated output
directories by repository publish scripts.


* Notes

1. AOG publishes content; repository-level scripts usually handle extra steps
   like link normalization, syntax post-processing, static asset copy, and
   deployment-specific aliasing.
2. If you rely on incremental git-aware publishing, keep repository history
   clean and commit source changes before publication.