Adds support for an alternate content root to api/watch

API.md

@@ -12,7 +12,14 @@
 
 
 Removes cache and output directories
-<br><sub>[source](https://github.com/borkdude/quickblog/blob/main/src/quickblog/api.clj#L493-L499)</sub>
+<br><sub>[source](https://github.com/borkdude/quickblog/blob/main/src/quickblog/api.clj#L580-L586)</sub>
+## `debug`
+``` clojure
+
+(debug & xs)
+```
+
+<sub>[source](https://github.com/borkdude/quickblog/blob/main/src/quickblog/api.clj#L277-L279)</sub>
 ## `migrate`
 ``` clojure
 
@@ -21,7 +28,7 @@ Removes cache and output directories
 
 
 Migrates from `posts.edn` to post-local metadata
-<br><sub>[source](https://github.com/borkdude/quickblog/blob/main/src/quickblog/api.clj#L501-L512)</sub>
+<br><sub>[source](https://github.com/borkdude/quickblog/blob/main/src/quickblog/api.clj#L588-L599)</sub>
 ## `new`
 ``` clojure
 
@@ -30,7 +37,7 @@ Migrates from `posts.edn` to post-local metadata
 
 
 Creates new `file` in posts dir.
-<br><sub>[source](https://github.com/borkdude/quickblog/blob/main/src/quickblog/api.clj#L466-L491)</sub>
+<br><sub>[source](https://github.com/borkdude/quickblog/blob/main/src/quickblog/api.clj#L524-L578)</sub>
 ## `quickblog`
 ``` clojure
 
@@ -39,7 +46,7 @@ Creates new `file` in posts dir.
 
 
 Alias for `render`
-<br><sub>[source](https://github.com/borkdude/quickblog/blob/main/src/quickblog/api.clj#L457-L460)</sub>
+<br><sub>[source](https://github.com/borkdude/quickblog/blob/main/src/quickblog/api.clj#L515-L518)</sub>
 ## `refresh-templates`
 ``` clojure
 
@@ -48,7 +55,7 @@ Alias for `render`
 
 
 Updates to latest default templates
-<br><sub>[source](https://github.com/borkdude/quickblog/blob/main/src/quickblog/api.clj#L514-L517)</sub>
+<br><sub>[source](https://github.com/borkdude/quickblog/blob/main/src/quickblog/api.clj#L601-L604)</sub>
 ## `render`
 ``` clojure
 
@@ -57,16 +64,34 @@ Updates to latest default templates
 
 
 Renders posts declared in `posts.edn` to `out-dir`.
-<br><sub>[source](https://github.com/borkdude/quickblog/blob/main/src/quickblog/api.clj#L421-L455)</sub>
+<br><sub>[source](https://github.com/borkdude/quickblog/blob/main/src/quickblog/api.clj#L475-L513)</sub>
 ## `serve`
 ``` clojure
 
 (serve opts)
+(serve opts block?)
+```
+
+
+Runs file-server on `port`. If `block?` is falsey, returns a zero-arity
+  `stop-server!` function that will stop the server when called.
+<br><sub>[source](https://github.com/borkdude/quickblog/blob/main/src/quickblog/api.clj#L606-L624)</sub>
+## `unwatch`
+``` clojure
+
+(unwatch watchers)
 ```
 
 
-Runs file-server on `port`.
-<br><sub>[source](https://github.com/borkdude/quickblog/blob/main/src/quickblog/api.clj#L519-L532)</sub>
+Stops each watcher in the list of `watchers`.
+<br><sub>[source](https://github.com/borkdude/quickblog/blob/main/src/quickblog/api.clj#L712-L717)</sub>
+## `update-cache-dir`
+``` clojure
+
+(update-cache-dir opts)
+```
+
+<sub>[source](https://github.com/borkdude/quickblog/blob/main/src/quickblog/api.clj#L190-L198)</sub>
 ## `watch`
 ``` clojure
 
@@ -75,8 +100,9 @@ Runs file-server on `port`.
 
 
 Watches posts, templates, and assets for changes. Runs file server using
-  `serve`.
-<br><sub>[source](https://github.com/borkdude/quickblog/blob/main/src/quickblog/api.clj#L536-L601)</sub>
+  `serve` (unless the `:serve` opt is `false`). If the `:block` opt is `false`,
+  returns a list of watchers that can be passed to `unwatch` to stop watching.
+<br><sub>[source](https://github.com/borkdude/quickblog/blob/main/src/quickblog/api.clj#L628-L710)</sub>
 # quickblog.cli 
 
 
@@ -89,15 +115,15 @@ Watches posts, templates, and assets for changes. Runs file server using
 (-main & args)
 ```
 
-<sub>[source](https://github.com/borkdude/quickblog/blob/main/src/quickblog/cli.clj#L143-L144)</sub>
+<sub>[source](https://github.com/borkdude/quickblog/blob/main/src/quickblog/cli.clj#L144-L145)</sub>
 ## `dispatch`
 ``` clojure
 
 (dispatch)
 (dispatch default-opts & args)
 ```
 
-<sub>[source](https://github.com/borkdude/quickblog/blob/main/src/quickblog/cli.clj#L127-L133)</sub>
+<sub>[source](https://github.com/borkdude/quickblog/blob/main/src/quickblog/cli.clj#L128-L134)</sub>
 ## `run`
 ``` clojure
 
@@ -106,4 +132,65 @@ Watches posts, templates, and assets for changes. Runs file server using
 
 
 Meant to be called using `clj -M:quickblog`; see Quickstart > Clojure in README
-<br><sub>[source](https://github.com/borkdude/quickblog/blob/main/src/quickblog/cli.clj#L135-L141)</sub>
+<br><sub>[source](https://github.com/borkdude/quickblog/blob/main/src/quickblog/cli.clj#L136-L142)</sub>
+# quickblog.internal.frontmatter 
+
+
+
+
+
+## `flatten-metadata`
+``` clojure
+
+(flatten-metadata metadata)
+```
+
+
+Given a list of maps which contain a single key/value, flatten them all into
+  a single map with all the leading spaces removed. If an empty list is provided
+  then return nil.
+<br><sub>[source](https://github.com/borkdude/quickblog/blob/main/src/quickblog/internal/frontmatter.clj#L20-L39)</sub>
+## `parse-edn-metadata-headers`
+``` clojure
+
+(parse-edn-metadata-headers lines-seq)
+```
+
+<sub>[source](https://github.com/borkdude/quickblog/blob/main/src/quickblog/internal/frontmatter.clj#L67-L77)</sub>
+## `parse-metadata-headers`
+``` clojure
+
+(parse-metadata-headers lines-seq)
+```
+
+
+Given a sequence of lines from a markdown document, attempt to parse a
+  metadata header if it exists. Accepts wiki, yaml, and edn formats.
+  Returns the parsed headers number of lines the metadata spans
+<br><sub>[source](https://github.com/borkdude/quickblog/blob/main/src/quickblog/internal/frontmatter.clj#L79-L95)</sub>
+## `parse-metadata-line`
+``` clojure
+
+(parse-metadata-line line)
+```
+
+
+Given a line of metadata header text return either a list containing a parsed
+  and normalizd key and the original text of the value, or if no header is found
+  (this is a continuation or new value from a pervious header key) simply
+  return the text. If a blank or invalid line is found return nil.
+<br><sub>[source](https://github.com/borkdude/quickblog/blob/main/src/quickblog/internal/frontmatter.clj#L6-L18)</sub>
+## `parse-wiki-metadata-headers`
+``` clojure
+
+(parse-wiki-metadata-headers lines-seq)
+```
+
+<sub>[source](https://github.com/borkdude/quickblog/blob/main/src/quickblog/internal/frontmatter.clj#L42-L49)</sub>
+## `parse-yaml-metadata-headers`
+``` clojure
+
+(parse-yaml-metadata-headers lines-seq)
+```
+
+<sub>[source](https://github.com/borkdude/quickblog/blob/main/src/quickblog/internal/frontmatter.clj#L53-L65)</sub>

CHANGELOG.md

@@ -4,6 +4,10 @@
 
 Instances of quickblog can be seen [here](https://github.com/borkdude/quickblog?tab=readme-ov-file#blogs-using-quickblog).
 
+## Unreleased
+
+- Add support for a blog contained within another website; see [Serving an alternate content root](README.md#serving-an-alternate-content-root) in README.  ([@jmglov](https://github.com/jmglov))
+
 ## 0.4.7 (2025-06-12)
 
 - Switch to [Nextjournal Markdown](https://github.com/nextjournal/markdown) for markdown rendering

README.md

@@ -314,6 +314,40 @@ Write a blog post here!
 any changes to the new post template will cause all of your existing posts to be
 re-rendered, which is probably not what you want!**
 
+## Serving an alternate content root
+
+If your website contains a blog not at the content root of the webserver (for
+example, https://example.com/blog), you may want `bb quickblog watch` to watch
+the blog directory whilst serving the blog directory's parent as the content
+root. Assuming that your website has a `bb.edn`, you can add a task similar to
+the following to accomplish this:
+
+``` clojure
+{:deps {io.github.borkdude/quickblog {:git/sha "LATEST-SHA-HERE"}}
+ :tasks
+ {:requires ([quickblog.api :as quickblog])
+  :init (def opts
+          {:out-dir "public"
+           ;; ...
+           :blog {:blog-title "Some cool blog"
+                  ;; ...
+                  :assets-dir "blog/assets"
+                  :out-dir "public/blog"
+                  :posts-dir "blog/posts"
+                  :templates-dir "blog/templates"}})
+
+  ;; ...
+
+  watch {:doc "Watch blog for changes"
+         :task (do
+                 (quickblog/watch (assoc (:blog opts)
+                                         :serve false
+                                         :block false))
+                 (quickblog/serve (assoc (:blog opts)
+                                         :out-dir (:out-dir opts))))}
+  }}
+```
+
 ## Breaking changes
 
 ### posts.edn removed