feat: add asciidoc live preview (#27)

- add live preview functionality for local doc development
- document setup prerequisites and usage in README
- include basic troubleshooting guide
- run pre-commit on all files

README.md

@@ -15,3 +15,97 @@ html mp11.html : mp11.adoc
 Noto font files are covered under the Open Font License:
 
 https://fonts.google.com/noto/use
+
+## Live Preview for AsciiDoc Documentation
+
+BoostLook includes a **live preview** feature to streamline local development and review of AsciiDoc documentation. This allows for automatic rendering and real-time browser preview of changes made to [`specimen.adoc`](/doc/specimen.adoc) and [`boostlook.css`](/boostlook.css) files.
+
+### Overview
+
+The preview functionality is handled by a Ruby script ([`boostlook_preview.rb`](./boostlook_preview.rb)). This script monitors AsciiDoc, HTML, and CSS files for changes, automatically rebuilding and opening the rendered HTML in your default web browser.
+
+---
+
+### Prerequisites
+
+Ensure the following dependencies are installed:
+
+- **Ruby** (>= 2.7 recommended)
+- **Asciidoctor** – Install via `gem install asciidoctor`
+- **Listen Gem** – Install via `gem install listen`
+- **Boost.Build (b2)** – Required for builds invoked by the script. Ensure it is installed and available in your system's PATH.
+
+---
+
+### Usage and Detailed Steps
+
+1. **Install Ruby and Required Gems**:
+    - Ensure Ruby is installed on your system. You can check by running:
+      ```bash
+      ruby -v
+      ```
+      If Ruby is not installed, follow the instructions on [ruby-lang.org](https://www.ruby-lang.org/en/documentation/installation/) to install it.
+    - Install Asciidoctor:
+      ```bash
+      gem install asciidoctor
+      ```
+    - Install the Listen gem:
+      ```bash
+      gem install listen
+      ```
+
+2. **Install Boost.Build (b2)**:
+    - Follow the instructions on the [Boost.Build website](https://boostorg.github.io/build/) to install `b2`.
+    - Ensure `b2` is available in your system's PATH by running:
+      ```bash
+      which b2
+      ```
+
+3. **Locate Specimen AsciiDoc File**:
+    - Place your AsciiDoc files in the `doc` directory. The default file is `doc/specimen.adoc`.
+    -  The default file structure should include:
+
+    ```
+     /boostlook
+       ├── doc
+       │   └── specimen.adoc <--
+       │   └── ...
+       ├── boostlook.css
+       └── boostlook_preview.rb
+       └── boostlook.rb
+       └── ...
+     ```
+
+4. **Navigate to the project directory**:
+    ```bash
+    cd /path/to/boostlook
+    ```
+
+5. **Run the preview script**:
+    - Ensure you're in the root folder
+    ```bash
+    ruby boostlook_preview.rb
+    ```
+
+6. **Edit and Preview**:
+    - Edit your AsciiDoc (specimen.adoc) or CSS (boostlook.css) files.
+    - The script will automatically detect changes and rebuild the documentation.
+    - Refresh the browser to see changes.
+
+7. **Refresh Your Browser** to view changes.
+
+---
+
+### Troubleshooting
+
+- **Script Not Running**:
+  - Ensure all prerequisites are installed correctly.
+  - Check for any error messages in the terminal and resolve them accordingly.
+
+- **Changes Not Reflecting**:
+  - Ensure the files being edited are within the monitored directories (`doc` and root directory).
+  - Verify that the browser is refreshing automatically or manually refresh the browser.
+
+- **Boost.Build (b2) Not Found**:
+  - Ensure `b2` is installed and available in your system's PATH.
+  - Run `which b2` to verify its availability.