From b3c95290897ce9bd442bf3a7f622d08668eb1430 Mon Sep 17 00:00:00 2001
From: Yusuf Cihan <user-github@ysfchn.com>
Date: Sun, 7 Jan 2024 16:19:05 +0300
Subject: [PATCH] Add more information about Vercel deployments (#2399)

* Add more information about Vercel

* Change wording and add specify version

* Update vercel.md
---
 .../documentation/deployment/vercel.md        | 82 +++++++++++++++++++
 1 file changed, 82 insertions(+)

diff --git a/docs/content/documentation/deployment/vercel.md b/docs/content/documentation/deployment/vercel.md
index 02a0233e62..072aedefb9 100644
--- a/docs/content/documentation/deployment/vercel.md
+++ b/docs/content/documentation/deployment/vercel.md
@@ -23,3 +23,85 @@ 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!
+
+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
+
+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.
+
+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 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
+{
+    "trailingSlash": true
+}
+```
+
+### 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/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:
+
+```json
+{
+    "cleanUrls": true
+}
+```
+
+### 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.
+
+To do that, set "Framework Preset" to "Other", and override "Install Command" to:
+
+```bash
+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.
+
+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": "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"
+}
+```
+
+## 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