From f46b357037577bfa444e5e343e1b3b19020d14ef Mon Sep 17 00:00:00 2001
From: Liam Bigelow <40188355+bglw@users.noreply.github.com>
Date: Sat, 9 Sep 2023 22:42:53 +1200
Subject: [PATCH] Document new initialization method

---
 docs/content/docs/api.md | 30 +++++++++++++++++++++++++++---
 1 file changed, 27 insertions(+), 3 deletions(-)

diff --git a/docs/content/docs/api.md b/docs/content/docs/api.md
index 9eda5c8e..3b1f831b 100644
--- a/docs/content/docs/api.md
+++ b/docs/content/docs/api.md
@@ -9,15 +9,39 @@ Pagefind can be accessed as an API directly from JavaScript, for you to build cu
 
 ## Initializing Pagefind
 
-Anywhere on your site, you can initialize Pagefind with:
+Anywhere on your site, import and initialize Pagefind with:
 
 ```js
 const pagefind = await import("/pagefind/pagefind.js");
+
+pagefind.init();
+```
+
+If your site is on a subpath, this should be included — e.g. in the CloudCannon documentation, we load `/documentation/pagefind/pagefind.js`.
+
+The call to `pagefind.init()` will load the Pagefind dependencies and the metadata about the site. Calling this method is optional, and if it is omitted initialization will happen when the first searching or filtering function is called.
+
+Calling `pagefind.init()` when your search interface gains focus will help the core dependencies load by the time a user types in their search query.
+
+## Configuring Pagefind
+
+Pagefind options can be set before running `pagefind.init()`:
+
+{{< diffcode >}}
+```js
+const pagefind = await import("/pagefind/pagefind.js");
+
++await pagefind.options({
++    bundlePath: "/custom-pagefind-directory/"
++});
+
+pagefind.init();
 ```
+{{< /diffcode >}}
 
-This will load the Pagefind library and the metadata about the site. If your site is on a subpath, this should be included — e.g. in the CloudCannon documentation, we load `/documentation/pagefind/pagefind.js`.
+Calls to `pagefind.options` may also be made after initialization, however passing in settings such as `bundlePath` will have no further impact.
 
-> If building your own search UI, it is a good idea to only run this import once your search component has received interaction. This saves the user from loading the Pagefind library on every page request.
+See all available options in [Configuring the Pagefind search in the browser](/docs/search-config/).
 
 ## Searching