More 1.0 documentation updates

docs/content/docs/_index.md

@@ -1,13 +1,13 @@
 ---
 title: "Getting Started with Pagefind"
-nav_title: "Getting Started"
+nav_title: "Quick Start"
 nav_section: Root
 weight: 7
 ---
 
-Pagefind runs after your static generator, and outputs a static search bundle to your generated site. Unlike many search libraries, you don't need to build a search index by hand — the index is generated for you from your generated site.
+Pagefind runs after your static generator, and outputs a static search bundle to your generated site. With Pagefind, you don't need to build a search index by hand — the index is generated for you from your generated site.
 
-Since Pagefind indexes your site _after_ it builds, we'll do things slightly out of order and add search UI first — so that it already exists on our built site when we go to index it.
+Since Pagefind indexes your site _after_ it builds, we'll do things slightly out of order and add a search UI first — so that it already exists on our built site when we go to index it.
 
 Pagefind provides a prebuilt search UI out of the box. Add the following snippet to a page of your choice:
 
@@ -17,7 +17,7 @@ Pagefind provides a prebuilt search UI out of the box. Add the following snippet
 <div id="search"></div>
 <script>
     window.addEventListener('DOMContentLoaded', (event) => {
-        new PagefindUI({ element: "#search" });
+        new PagefindUI({ element: "#search", showSubResults: true });
     });
 </script>
 ```
@@ -30,9 +30,9 @@ Now build your site to an output directory — this guide assumes that you're ru
 
 ## Indexing your site
 
-The easiest way to run pagefind is through npx, where `--site` points to the output directory of your static site generator. We'll also add `--serve` so that we can view our final site right away.
+The easiest way to run pagefind is through npx. If you don't have Node and npm installed, or want to install Pagefind another way, see the [Installing Pagefind](/docs/installation/) guide.
 
-> Note that Pagefind itself does not have any server component — the search integration is fully baked into your static site. The `--serve` flag here is a shortcut for running Pagefind, followed by serving your output site through any static web server.
+Run the following command from your terminal, where `--site` points to the output directory of your static site generator. We'll also add `--serve` so that we can view our final site right away.
 
 ```bash
 npx -y pagefind --site public --serve
@@ -49,7 +49,9 @@ Finished in 2.357 seconds
 
 We can see that a bunch of content was indexed, and Pagefind will be running a preview server (likely on [:1414](http://localhost:1414)).
 
-Loading this in your browser, you should see a search input on your page. Have a play, and bask in how easy that was to integrate.
+> Note that Pagefind itself does not have any server component — the search integration is fully baked into your static site. The `--serve` flag here is a shortcut for running Pagefind, followed by serving your output site through any static web server.
+
+Loading this in your browser, you should see a search input on your page. Try searching for some content and you will see results appear from your site.
 
 The last required step is to run Pagefind after building your site on your CMS or hosting platform. If you're a CloudCannon user, add a [`.cloudcannon/postbuild`](https://cloudcannon.com/documentation/articles/extending-your-build-process-with-hooks/) file containing the npx command above (minus the `--serve` flag). For other platforms, set up an equivalent command to run after your site build — the end goal is that Pagefind will run after every build of your site before it is deployed.
 

docs/content/docs/config-options.md

@@ -1,13 +1,16 @@
 ---
-title: "Configuring the Pagefind CLI"
-nav_title: "Pagefind CLI config"
-nav_section: Installing
-weight: 3
+title: "Pagefind CLI configuration options"
+nav_title: "CLI config options"
+nav_section: Pagefind CLI Reference
+weight: 31
 ---
 
-The Pagefind CLI has the following options:
+The Pagefind CLI has the following options.  
+These can be set via any [configuration source](http://localhost:1313/docs/config-sources/).
 
-> For configuring the Pagefind search in the browser, see [Pagefind Search Config](/docs/search-config/). For configuring the Pagefind UI, see [Pagefind UI](/docs/ui/).
+> These configuration options only apply when running the Pagefind indexing tool on your site.
+> For configuring Pagefind search in the browser, see [Pagefind Search Config](/docs/search-config/).  
+> For configuring the Pagefind Default UI, see [Pagefind UI](/docs/ui/).
 
 ## Required arguments
 

docs/content/docs/config-sources.md

@@ -1,8 +1,8 @@
 ---
 title: "Pagefind CLI configuration sources"
-nav_title: "Config sources"
-nav_section: Installing
-weight: 2
+nav_title: "CLI config sources"
+nav_section: Pagefind CLI Reference
+weight: 30
 ---
 
 Pagefind can be configured through CLI flags, environment variables, or configuration files. Values will be merged from all sources, with CLI flags overriding environment variables, and environment variables overriding configuration files.

docs/content/docs/default-ui-filtering.md

@@ -0,0 +1,13 @@
+---
+title: "Filtering results with the Pagefind Default UI"
+nav_title: "Filtering with the Default UI"
+nav_section: Filtering
+weight: 3
+---
+
+Pagefind's Default UI supports filters and will show them in a sidebar if they are present in your index.
+
+The Default UI will also show a count beside each filter, representing the number of results available within that filter, taking the current search term and toggled filters into account.  
+By default, filters with no remaining pages will still be shown. This can be disabled by setting the [`showEmptyFilters`](/docs/ui/#show-empty-filters) option to `false`.
+
+Currently, the Default UI treats all filters as "AND" filters, meaning pages will only be shown if they match all toggled filters.

docs/content/docs/filtering.md

@@ -1,59 +1,102 @@
 ---
 title: "Setting up filters"
 nav_title: "Setting up filters"
-nav_section: Indexing
-weight: 4
+nav_section: Filtering
+weight: 10
 ---
 
-Pagefind supports filtering your content while searching. This is configured through the `data-pagefind-filter` attribute.
+To configure filters in Pagefind, pages are assocated to filter keys and values using data attributes.
 
-## Tagging an element as a filter
+## Capturing a filter value from an element
 
+{{< diffcode >}}
 ```html
-<h1>Hello World</h1>
-<p>Author: <span data-pagefind-filter="author">CloudCannon</span></p>
+<h1>My Blog Post</h1>
+<p>
+    Author:
++    <span data-pagefind-filter="author">CloudCannon</span>
+</p>
 ```
+{{< /diffcode >}}
 
 An element tagged with `data-pagefind-filter` will associate that page with the filter name, and capture the contents of the element as the filter value. In the above example, the page would be tagged as `author: ["CloudCannon"]`.
 
 Filters can have multiple values per page, so the following is also valid:
 
+{{< diffcode >}}
 ```html
 <h1>Hello World</h1>
-<p>Authors:
-    <span data-pagefind-filter="author">CloudCannon</span>
+<p>
+    Authors:
++    <span data-pagefind-filter="author">CloudCannon</span>
     and
-    <span data-pagefind-filter="author">Liam Bigelow</span>
++    <span data-pagefind-filter="author">Liam Bigelow</span>
 </p>
 ```
+{{< /diffcode >}}
 
-## Tagging an attribute as a filter
+Which produces: `author: ["CloudCannon", "Liam Bigelow"]`.
 
-If your filter values exists as an attribute, you can use the syntax `filter_name[html_attribute]`
+## Capturing a filter value from an attribute
 
+If the data you want to filter on exists as an attribute, you can use the syntax `filter_name[html_attribute]`"
+
+{{< diffcode >}}
 ```html
 <head>
     <meta 
-        data-pagefind-filter="author[content]"
-        content="CloudCannon"
++        data-pagefind-filter="author[content]"
+        content="Pagefind"
         property="og:site_name">
 </head>
 ```
+{{< /diffcode >}}
+
+This will capture the filter value from the attribute specified, in this case producing `author: ["Pagefind"]`.
 
-## Tagging a filter inline
+## Specifying a filter inline
 
-If your value doesn't already exist on the page, you can simply use the syntax `filter_name:value`
+If your value doesn't already exist on the page, you can use the syntax `filter_name:value`:
 
+{{< diffcode >}}
 ```html
 <h1 data-pagefind-filter="author:CloudCannon">Hello World</h1>
 ```
+{{< /diffcode >}}
 
-## Advanced
+This will tag this page as `author: ["CloudCannon"]`. The element this is set on does not matter, meaning this attribute can be located anywhere that is convenient in your site templating.
 
-The filter syntax follows the same rules as the metadata syntax, see [Defining multiple metadata keys on a single element](/docs/metadata/#defining-multiple-metadata-keys-on-a-single-element) for more detail.
+## Specifying multiple filters on a single element
+
+Filter captures may be comma seperated and all will apply. The exception is specifying a filter inline, which may only be the last item in a list.
+
+For example:
+
+{{< diffcode >}}
+```html
+<h1
+    data-section="Documentation"
+    data-category="Article"
++    data-pagefind-meta="heading, tag[data-section], tag[data-category], author:Freeform text, captured to the end">
+        Hello World
+</h1>
+```
+{{< /diffcode >}}
+
+This will produce the filter values for the page:
+
+```json
+{
+    "heading": ["Hello World"],
+    "tag": ["Documentation", "Article"],
+    "author": ["Freeform text, captured to the end"]
+}
+```
 
 ## Notes
 
 > The `data-pagefind-filter` attribute does not need to be within the `<body>`, or the `data-pagefind-body` tag. 
 
-> The `data-pagefind-filter` attribute will still apply if set on or within a `data-pagefind-ignore` element.
+> The `data-pagefind-filter` attribute will still apply if set on or within a `data-pagefind-ignore` element.
+
+> The keys `any`, `all`, `none`, and `not` are reserved and can't be used as filter keys.

docs/content/docs/indexing.md

@@ -1,17 +1,17 @@
 ---
-title: "Configuring how content is indexed"
+title: "Configuring what content is indexed"
 nav_title: "Customizing the index"
 nav_section: Indexing
 weight: 2
 ---
 
-You can control how your site is indexed by using various `data-pagefind-*` tags in your templates.
+You can control what content on your site is indexed via `data-pagefind-*` tags on your HTML elements.
 
-## Limiting what content is indexed
+## Limiting what sections of a page are indexed
 
-By default, Pagefind indexes all content inside your `<body>` element, with some exceptions — elements such as `<nav>`, `<script>`, and `<form>` will be skipped automatically. 
+By default, Pagefind starts indexing from your `<body>` element.
 
-To refine indexing further, you can tag your main content area with `data-pagefind-body`:
+To narrow this down, you can tag your main content area with `data-pagefind-body`:
 
 ```html
 <body>
@@ -25,13 +25,23 @@ To refine indexing further, you can tag your main content area with `data-pagefi
 </body>
 ```
 
-> If `data-pagefind-body` is found anywhere on your site, any pages without this attribute will be removed from your index. This means that if you tag your blog post layout with `data-pagefind-body`, other pages like your homepage will no longer appear in search results. This is usually what you want — if not, just add `data-pagefind-body` there as well.
+If `data-pagefind-body` is found anywhere on your site, any pages without this attribute will not be indexed. This means that if you tag your blog post layout with `data-pagefind-body`, other pages like your homepage will no longer appear in search results. This is usually what you want — if not, just add `data-pagefind-body` there as well.
+
+Multiple `data-pagefind-body` elements may exist on a page, and their content will be combined.
 
 > Note that metadata and filters that are set outside of this element will still be used. If this is not what you want, see the [root selector](/docs/config-options/#root-selector) configuration option.
 
+## Removing pages from Pagefind's index
+
+Once a `data-pagefind-body` attribute exists on any page of your site, any pages without this attribute will not be indexed. As such, the best way to remove pages is by adding `data-pagefind-body` to the pages you **would** like to index.
+
+If this isn't possible, see the [Pagefind CLI's glob option](/docs/config-options/#glob) to limit the files that Pagefind reads.
+
 ## Removing individual elements from the index
 
-If you have a component that you don't want to include in your search index, you can tag it with `data-pagefind-ignore`:
+Pagefind has some built-in elements that are not indexed. These are organizational elements such as `<nav>` and `<footer>`, or more programmatic elements such as `<script>` and `<form>`. These elements will be skipped over automatically.
+
+If you have further elements that you don't want to include in your search index, you can tag them with `data-pagefind-ignore`:
 
 ```html
 <main data-pagefind-body>
@@ -43,7 +53,7 @@ If you have a component that you don't want to include in your search index, you
 </main>
 ```
 
-The `data-pagefind-ignore` attribute can optionally take a value of `index` or `all`. Omitting a value implies `index`, which will exclude the element and all children from the search index, but will still process filters and metadata within the element, and will still try to detect a default title or image found within this element.
+The `data-pagefind-ignore` attribute can optionally take a value of `index` or `all`. Omitting a value implies `index`, which will exclude the element and all children from the search index while still processing filters and metadata within the element, and will still try to detect a default title or image found within this element.
 
 Specifying `all` will exclude the element and its children from all processing.
 
@@ -59,11 +69,11 @@ Specifying `all` will exclude the element and its children from all processing.
 </aside>
 ```
 
-> To remove elements without changing your templating, see the [exclude selectors](/docs/config-options/#exclude-selectors) CLI option.
+> To remove elements without changing your templating, see the [Pagefind CLI's exclude selectors option](/docs/config-options/#exclude-selectors).
 
-## Indexing attributes
+## Adding HTML attributes to the index
 
-Attributes of HTML elements can be added to the main search index with the `data-pagefind-index-attrs` attribute:
+Attributes of HTML elements can be added to the search index with the `data-pagefind-index-attrs` attribute:
 
 ```html
 <h1>Condimentum Nullam</h1>
@@ -74,7 +84,8 @@ Attributes of HTML elements can be added to the main search index with the `data
 <p>Nullam id dolor id nibh ultricies.</p>
 ```
 
-This will be indexed as: `Condimentum Nullam. Image Title. Image Alt. Nullam id dolor id nibh ultricies.`
+This attribute takes a comma-separated list of other attributes to include inline with the indexed content.  
+The above example will be indexed as: `Condimentum Nullam. Image Title. Image Alt. Nullam id dolor id nibh ultricies.`
 
 ## Ranking content higher with weights
 

docs/content/docs/installation.md

@@ -1,8 +1,8 @@
 ---
 title: "Installing and running Pagefind"
-nav_title: "Installation"
-nav_section: Installing
-weight: 1
+nav_title: "Installing Pagefind"
+nav_section: Pagefind CLI Reference
+weight: 29
 ---
 
 Pagefind is a static binary with no dynamic dependencies, so in most cases will be simple to install and run. Pagefind is currently supported on Windows, macOS, and x86-64 Linux distributions.
@@ -13,7 +13,7 @@ Pagefind is a static binary with no dynamic dependencies, so in most cases will
 npx pagefind --site "public"
 ```
 
-Pagefind publishes a [wrapper package through npm](https://www.npmjs.com/package/pagefind), which is the easiest way to get started. This package will download the correct [binary of the latest release](https://github.com/CloudCannon/pagefind/releases) from GitHub for your platform and run it.
+Pagefind publishes a [wrapper package through npm](https://www.npmjs.com/package/pagefind), which is the easiest way to get started. This package will download the correct [binary of the latest release](https://github.com/CloudCannon/pagefind/releases) as an npm dependency for your platform and run it.
 
 Specific versions can be run by passing a version tag: