Usage

👉 Prebuild a single HTML file:

pree build docs/my-page.html site/my-page.html

This prebuilds docs/my-page.html into site/my-page.html:

 🧬

Pre-renders web components, using declarative shadow DOM.

 🏗️ Resolves metadata and layouts, 👻Removes build-only scripts and components.

👉 Prebuild an entire directory:

pree build docs site

Copies over the contents of docs into site, then prebuilds all HTML files, except the ones excluded by CLI options or configuration. Files beginning with an underline (e.g. _layout.html) are excluded by default.


👉 Preview your website:

pree view docs
👀Loads your website without prebuilding it, 🏗️Still resolves metadata and layouts, 🔃Live reloads on change, 📁Also lists directory content for easy navigation.

Performance of your pages in preview mode is much slower than in production mode, since the content is not prebuilt. To double check the performance of your prebuilt website, first build it:

pree build docs site

Then check the prebuilt website:

pree check site

Asset Management

pree is NOT an asset manager. It copies the contents of the directory it should build, so assets located in that directory can safely be referenced in your HTML files:

 docs/
  ├─ assets/
  │   ├─ styles.css
  │   └─ logo.png
  └─ my-page.html

<link rel="stylesheet" href="assets/styles.css">
<img src="assets/logo.png">

Sometimes the base URL for your website is not the root of your domain. For example, in GitHub Pages, without a custom domain, your website will be hosted at https://username.github.io/repo/. In this case, you can set the base URL in the head of your HTML files:

<base href="/repo/">

And specify a base option to pree:

pree build docs site -b repo

💡 IMPORTANT

<base> tag doesn't play nice with relative paths in subdirectories. For example, for a project like this:

blog
 └─ post-1/
     ├─ index.html
     └─ figure.png

If you set the base URL to /blog/, the following won't work:

<!-- blog/post-1/index.html -->

<base href="/blog/">

...

<img src="./figure.png">

<!-- ❌ Here, ./figure.png is not resolved relative to index.html.
     It is resolved relative to /blog/, which is the base URL.
     i.e., it becomes /blog/figure.png, which is WRONG. -->

If you want to use relative paths like this, DO NOT use the <base> tag. You can still provide the base option to pree so that it emulates your hosting environment.

Config File

👉 Create a config file so you don't have to specify pree's options everytime:

# .pree.yml
base: repo
src: docs
dest: site

pree will look for .pree.yml in the current working directory, and use it as the default configuration:

pree view          # 👈 this is equal to `pree view docs`

pree build         # 👈 this is equal to `pree view build`

pree check         # 👈 this is equal to `pree check site`

📖

Read this for a comprehensive list of options.


pree logo