From aceb52804dc7d3308b4da5ae2100e2f9c0978dab Mon Sep 17 00:00:00 2001 From: Yusuf Cihan Date: Wed, 3 Jan 2024 19:20:04 +0300 Subject: [PATCH 1/3] Add more information about Vercel --- .../documentation/deployment/vercel.md | 73 +++++++++++++++++++ 1 file changed, 73 insertions(+) diff --git a/docs/content/documentation/deployment/vercel.md b/docs/content/documentation/deployment/vercel.md index 02a0233e62..0ab8376b72 100644 --- a/docs/content/documentation/deployment/vercel.md +++ b/docs/content/documentation/deployment/vercel.md @@ -23,3 +23,76 @@ You can learn more about how to setup a custom domain and how to get the most ou [via their documentation.](https://vercel.com/docs) After you click the blue "Deploy" button, it's off to the races! + +## Troubleshooting + +### `GLIBC_X.XX` not found + +This is because Vercel's build images comes with an older glibc version whereas Zola +depends on a newer glibc. However, Vercel provides a newer build image which can be used in +deployments by setting Node.js version to "20.x", allowing Zola to work properly. + +## Additional options + +### Enable trailing slashes + +Visiting a page without trailing slash may break relative paths, so you might want to configure +Vercel to always redirect paths with a trailing slash. By default, redirecting to a trailing +slash is not enabled on Vercel. + +If enabled, for example the `/about` path will redirect to `/about/`. Paths with a file extension +will not redirect to a trailing slash, for example `/styles.css` will stay as-is. + +To do that, create a file in the root of your git repository named `vercel.json` +(if it doesn't exists already), and set this option: + +```json +{ + "trailingSlash": true +} +``` + +### Prefer clean URLs + +When enabled, all HTML files will be served without their file extension, so visitors will see +`/about` instead of `/about.html` while navigating through your website. + +To do that, create a file in the root of your git repository named `vercel.json` +(if it doesn't exists already), and set this option: + +```json +{ + "cleanUrls": true +} +``` + +### Using a newer Zola version + +Vercel's built-in Zola support may be outdated, so you may want to use the latest Zola version. +To do that, set "Framework Preset" to "Other", and override "Install Command" to: + +```bash +curl -fsS https://api.github.com/repos/getzola/zola/releases/latest | grep -oP '"browser_download_url": ?"\K(.+linux-gnu.tar.gz)' | xargs -n 1 curl -fsSL -o zola.tar.gz && tar -xzvf zola.tar.gz +``` + +This command will fetch the latest release from GitHub, download the archive and extract it. + +Then, set "Build Command" to `./zola build`. Now Vercel will use the downloaded Zola +binary to build the documentation instead of using the built-in one. + +If you prefer to use `vercel.json` instead, (which overrides the options set in the dashboard) +you can use this configuration. + +```json +{ + "framework": null, + "installCommand": "curl -fsS https://api.github.com/repos/getzola/zola/releases/latest | grep -oP '\"browser_download_url\": ?\"\\K(.+linux-gnu.tar.gz)' | xargs -n 1 curl -fsSL -o zola.tar.gz && tar -xzvf zola.tar.gz", + "buildCommand": "./zola build", + "outputDirectory": "public" +} +``` + +## See also + +See [Vercel's own documentation](https://vercel.com/docs/projects/project-configuration) +for all available options in `vercel.json`. \ No newline at end of file From b968443679d74495e21b690883d734c328686316 Mon Sep 17 00:00:00 2001 From: Yusuf Cihan Date: Thu, 4 Jan 2024 13:39:36 +0300 Subject: [PATCH 2/3] Change wording and add specify version --- .../documentation/deployment/vercel.md | 29 ++++++++++++------- 1 file changed, 19 insertions(+), 10 deletions(-) diff --git a/docs/content/documentation/deployment/vercel.md b/docs/content/documentation/deployment/vercel.md index 0ab8376b72..97113227c2 100644 --- a/docs/content/documentation/deployment/vercel.md +++ b/docs/content/documentation/deployment/vercel.md @@ -24,6 +24,9 @@ You can learn more about how to setup a custom domain and how to get the most ou After you click the blue "Deploy" button, it's off to the races! +To use a specific version of Zola, set [`ZOLA_VERSION`](https://vercel.com/docs/deployments/environments#specifying-framework-versions) environment variable in project settings to a valid +release tag, for example `0.17.2`. + ## Troubleshooting ### `GLIBC_X.XX` not found @@ -40,10 +43,12 @@ Visiting a page without trailing slash may break relative paths, so you might wa Vercel to always redirect paths with a trailing slash. By default, redirecting to a trailing slash is not enabled on Vercel. -If enabled, for example the `/about` path will redirect to `/about/`. Paths with a file extension -will not redirect to a trailing slash, for example `/styles.css` will stay as-is. +For example if you have an `about.md` file, and when visiting the path without a trailing +slash, like `/about`, Vercel will redirect with trailing slash, resulting in `/about/`. +Paths with a file extension will not redirect to a trailing slash, for example if you +have a static file named `favicon.ico`, it will stay as-is. -To do that, create a file in the root of your git repository named `vercel.json` +To enable that, create a file in the root of your git repository named `vercel.json` (if it doesn't exists already), and set this option: ```json @@ -54,10 +59,11 @@ To do that, create a file in the root of your git repository named `vercel.json` ### Prefer clean URLs -When enabled, all HTML files will be served without their file extension, so visitors will see -`/about` instead of `/about.html` while navigating through your website. +When enabled, all HTML files will be served without their file extension. For example +if you have an `about.md` file, Zola will generate a `about.html` file, but Vercel +will serve the file as `/about`, without its `.html` suffix. -To do that, create a file in the root of your git repository named `vercel.json` +To enable that, create a file in the root of your git repository named `vercel.json` (if it doesn't exists already), and set this option: ```json @@ -66,13 +72,16 @@ To do that, create a file in the root of your git repository named `vercel.json` } ``` -### Using a newer Zola version +### Using a custom Zola binary + +If you want to use your own Zola binary that published on GitHub, or if you want to +always use the latest version of Zola, you can run a shell command to grab the +latest release from GitHub. -Vercel's built-in Zola support may be outdated, so you may want to use the latest Zola version. To do that, set "Framework Preset" to "Other", and override "Install Command" to: ```bash -curl -fsS https://api.github.com/repos/getzola/zola/releases/latest | grep -oP '"browser_download_url": ?"\K(.+linux-gnu.tar.gz)' | xargs -n 1 curl -fsSL -o zola.tar.gz && tar -xzvf zola.tar.gz +REPO="getzola/zola"; curl -fsS https://api.github.com/repos/${REPO}/releases/latest | grep -oP '"browser_download_url": ?"\K(.+linux-gnu.tar.gz)' | xargs -n 1 curl -fsSL -o zola.tar.gz && tar -xzvf zola.tar.gz ``` This command will fetch the latest release from GitHub, download the archive and extract it. @@ -86,7 +95,7 @@ you can use this configuration. ```json { "framework": null, - "installCommand": "curl -fsS https://api.github.com/repos/getzola/zola/releases/latest | grep -oP '\"browser_download_url\": ?\"\\K(.+linux-gnu.tar.gz)' | xargs -n 1 curl -fsSL -o zola.tar.gz && tar -xzvf zola.tar.gz", + "installCommand": "REPO=\"getzola/zola\"; curl -fsS https://api.github.com/repos/${REPO}/releases/latest | grep -oP '\"browser_download_url\": ?\"\\K(.+linux-gnu.tar.gz)' | xargs -n 1 curl -fsSL -o zola.tar.gz && tar -xzvf zola.tar.gz", "buildCommand": "./zola build", "outputDirectory": "public" } From 77bd157c956b44ceb6fa3cd189df6dde8c7cb596 Mon Sep 17 00:00:00 2001 From: Yusuf Cihan Date: Sat, 6 Jan 2024 11:47:25 +0300 Subject: [PATCH 3/3] Update vercel.md --- docs/content/documentation/deployment/vercel.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/content/documentation/deployment/vercel.md b/docs/content/documentation/deployment/vercel.md index 97113227c2..072aedefb9 100644 --- a/docs/content/documentation/deployment/vercel.md +++ b/docs/content/documentation/deployment/vercel.md @@ -60,8 +60,8 @@ To enable that, create a file in the root of your git repository named `vercel.j ### Prefer clean URLs When enabled, all HTML files will be served without their file extension. For example -if you have an `about.md` file, Zola will generate a `about.html` file, but Vercel -will serve the file as `/about`, without its `.html` suffix. +if you have an `about.md` file, Zola will generate a `about/index.html` file, but Vercel +will serve the file as `/about`, without its `index.html` suffix. To enable that, create a file in the root of your git repository named `vercel.json` (if it doesn't exists already), and set this option: