diff --git a/docs/content/docs/_index.md b/docs/content/docs/_index.md index 274c81fc..87fdf08c 100644 --- a/docs/content/docs/_index.md +++ b/docs/content/docs/_index.md @@ -30,15 +30,22 @@ 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. If you don't have Node and npm installed, or want to install Pagefind another way, see the [Installing Pagefind](/docs/installation/) guide. +The easiest way to run Pagefind is through one of the official wrapper packages. If you don't have Node or Python installed, or want to install Pagefind another way, see the [Installing Pagefind](/docs/installation/) guide. -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. +To use the Node wrapper, 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 ``` -You should see some output along the lines of: +Using the Python wrapper is similar, but requires an initial install: + +```bash +python3 -m pip install 'pagefind[extended]' +python3 -m pagefind --site public --serve +``` + +Regardless of the command you choose, after Pagefind has downloaded you should see some output along the lines of: ``` Indexed 2496 pages Indexed 22852 words diff --git a/docs/content/docs/installation.md b/docs/content/docs/installation.md index e4ffcfea..f63fcfbb 100644 --- a/docs/content/docs/installation.md +++ b/docs/content/docs/installation.md @@ -5,25 +5,55 @@ nav_section: References weight: 49 --- -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. +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 Linux distributions. ## Running via npx +For users with a NodeJS toolchain already installed, Pagefind publishes a [wrapper package through npm](https://www.npmjs.com/package/pagefind): + ```bash 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) as an npm dependency for your platform and run it. +This package includes the correct [binary of the relevant release](https://github.com/CloudCannon/pagefind/releases) as a dependency for your platform. Specific versions can be run by passing a version tag: ```bash npx pagefind@latest --site "public" -npx pagefind@v0.2.0 --site "public" +npx pagefind@v1.1.1 --site "public" +``` + +Running Pagefind via npx will always download the `pagefind_extended` release, which includes specialized support for indexing Chinese and Japanese pages. + +> Pagefind's npm package can also be imported and controlled from a script. See the [Node API documentation](/docs/node-api/) for details. + +## Running via Python + +For users with a Python toolchain already installed, Pagefind publishes a [wrapper package through pypi](https://pypi.org/project/pagefind/): + +```bash +python3 -m pip install 'pagefind[extended]' +python3 -m pagefind --site "public" +``` + +This package includes the correct [binary of the relevant release](https://github.com/CloudCannon/pagefind/releases) as a dependency for your platform. + +Specific versions can be installed by passing a version: + +```bash +python3 -m pip install 'pagefind[extended]==1.1.1' +``` + +The above example shows installing the `pagefind_extended` release, which includes specialized support for indexing Chinese and Japanese pages. +To install the smaller standard release, run: + +```bash +python3 -m pip install 'pagefind[bin]' ``` -> Running Pagefind via npx will download the `pagefind_extended` release, which includes specialized support for indexing Chinese and Japanese pages. +> Pagefind's Python package can also be imported and controlled from a script. See the [Python API documentation](/docs/py-api/) for details. ## Downloading a precompiled binary diff --git a/docs/content/docs/py-api.md b/docs/content/docs/py-api.md index c12758bd..dcd11aa4 100644 --- a/docs/content/docs/py-api.md +++ b/docs/content/docs/py-api.md @@ -13,6 +13,23 @@ There are situations where using this Python package is beneficial: - Users looking to index their site and augment that index with extra non-HTML pages can run a standard Pagefind crawl with [`add_directory`](#indexadd_directory) and augment it with [`add_custom_record`](#indexadd_custom_record). - Users looking to use Pagefind's engine for searching miscellaneous content such as PDFs or subtitles, where [`add_custom_record`](#indexadd_custom_record) can be used to build the entire index from scratch. +## Installation + +To install just the Python wrapper, and use a `pagefind` executable from your system: +```bash +python3 -m pip install 'pagefind' +``` + +To install the Python wrapper as well as the standard binary for your platform: +```bash +python3 -m pip install 'pagefind[bin]' +``` + +To install the Python wrapper as well as the extended binary for your platform: +```bash +python3 -m pip install 'pagefind[extended]' +``` + ## Example Usage @@ -143,7 +160,7 @@ If the `path` provided is relative, it will be relative to the current working d indexed_dir = await index.add_directory("./public", glob="**.{html}") ``` -Optionally, a custom `glob` can be supplied which controls which files Pagefind will consume within the directory. The default is shown, and the `glob` option can be omitted entirely. +Optionally, a custom `glob` can be supplied which controls which files Pagefind will consume within the directory. The default is shown, and the `glob` option can be omitted entirely. See [Wax patterns documentation](https://github.com/olson-sean-k/wax#patterns) for more details. ## index.add_html_file @@ -206,14 +223,14 @@ page_meta: dict[str, str] = custom_record["page_meta"] The `url`, `content`, and `language` fields are all required. `language` should be an [ISO 639-1 code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes). -`meta` is optional, and is strictly a flat object of keys to string values. +`meta` is optional, and is strictly a flat object of keys to string values. See the [Metadata documentation](https://pagefind.app/docs/metadata/) for semantics. -`filters` is optional, and is strictly a flat object of keys to arrays of string values. +`filters` is optional, and is strictly a flat object of keys to arrays of string values. See the [Filters documentation](https://pagefind.app/docs/filtering/) for semantics. -`sort` is optional, and is strictly a flat object of keys to string values. -See the [Sort documentation](https://pagefind.app/docs/sorts/) for semantics. +`sort` is optional, and is strictly a flat object of keys to string values. +See the [Sort documentation](https://pagefind.app/docs/sorts/) for semantics. *When Pagefind is processing an index, number-like strings will be sorted numerically rather than alphabetically. As such, the value passed in should be `"20"` and not `20`* If successful, the `file` object is returned containing metadata about the completed indexing.