Placez votre documentation dans un sous-dossier avec Vercel

Suivez ce guide pour héberger votre centre d'aide Ferndesk dans un sous-dossier personnalisé (comme yourdomain.com/help) en utilisant le proxying d'origine externe de Vercel.

Cela prend environ 10 minutes et nécessite un projet Vercel dans lequel vous pouvez ajouter un fichier de configuration vercel.json.

Vous êtes bloqué ? Contactez [email protected] et nous vous aiderons à terminer votre configuration.

Prérequis

Un espace de travail Ferndesk avec un accès administrateur
Un projet Vercel desservant votre site web principal
L'accès pour ajouter un fichier vercel.json à la racine de votre projet

Étape 1 : Configurer le sous-dossier dans Ferndesk

Tout d'abord, configurez votre centre d'aide Ferndesk pour utiliser un chemin de sous-dossier personnalisé.

Open Help Center settings

Connectez-vous à votre espace de travail Ferndesk, développez Help Center dans la barre latérale gauche, puis cliquez sur Customize.

Select Custom sub-folder

Cliquez sur Custom domain.

Sélectionnez l'option Custom sub-folder.

Enter your domain and subfolder

Entrez votre domaine dans le champ Domain (par exemple, www.example.com), puis entrez le chemin du sous-dossier souhaité dans le champ Subdirectory (par exemple, /help ou /docs).

Save and copy the Ferndesk host

Cliquez sur Configure sub-folder. Une fois configuré, copiez l'hôte proxy Ferndesk (par exemple, acme.hc.ferndesk.com) — vous en aurez besoin pour la configuration Vercel.

Utilisez votre nom d'hôte de production Vercel exact (par exemple, www.example.com), pas un nom d'hôte de déploiement de prévisualisation. Si le nom d'hôte change après le premier déploiement, des entrées de cache obsolètes peuvent persister.

Étape 2 : Ajouter la configuration de routage Vercel

Créez ou mettez à jour le fichier vercel.json à la racine de votre projet pour transférer les requêtes vers Ferndesk. Cette configuration utilise les routes de Vercel avec des transformations d'en-tête de requête pour envoyer à Ferndesk le chemin de base et les informations d'hôte requis.

Create or open vercel.json

Si vous n'avez pas encore de fichier vercel.json à la racine de votre projet, créez-en un. Si vous en avez déjà un, ouvrez-le pour le modifier.

Add the configuration

Collez la configuration ci-dessous dans votre fichier vercel.json. Remplacez les espaces réservés par vos valeurs réelles :

PUBLIC_HOST — votre nom d'hôte de production Vercel (par exemple, www.example.com)
FERNDESK_HOST — l'hôte Ferndesk que vous avez copié depuis le tableau de bord Ferndesk (par exemple, acme.hc.ferndesk.com)
BASE_PATH — le chemin de votre sous-dossier, incluant le slash de début (par exemple, /help)

{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "headers": [
    {
      "source": "/_ferndesk",
      "headers": [
        { "key": "x-vercel-enable-rewrite-caching", "value": "0" }
      ]
    },
    {
      "source": "/_ferndesk/:match*",
      "headers": [
        { "key": "x-vercel-enable-rewrite-caching", "value": "0" }
      ]
    },
    {
      "source": "__BASE_PATH__",
      "headers": [
        { "key": "x-vercel-enable-rewrite-caching", "value": "0" }
      ]
    },
    {
      "source": "__BASE_PATH__/:match*",
      "headers": [
        { "key": "x-vercel-enable-rewrite-caching", "value": "0" }
      ]
    }
  ],
  "routes": [
    {
      "src": "/_ferndesk",
      "dest": "https://__FERNDESK_HOST____BASE_PATH__/_ferndesk",
      "transforms": [
        { "type": "request.headers", "op": "set", "target": { "key": "x-ferndesk-base-path" }, "args": "__BASE_PATH__" },
        { "type": "request.headers", "op": "set", "target": { "key": "x-forwarded-host" }, "args": "__PUBLIC_HOST__" },
        { "type": "request.headers", "op": "set", "target": { "key": "x-ferndesk-original-host" }, "args": "__PUBLIC_HOST__" }
      ]
    },
    {
      "src": "/_ferndesk/(.*)",
      "dest": "https://__FERNDESK_HOST____BASE_PATH__/_ferndesk/$1",
      "transforms": [
        { "type": "request.headers", "op": "set", "target": { "key": "x-ferndesk-base-path" }, "args": "__BASE_PATH__" },
        { "type": "request.headers", "op": "set", "target": { "key": "x-forwarded-host" }, "args": "__PUBLIC_HOST__" },
        { "type": "request.headers", "op": "set", "target": { "key": "x-ferndesk-original-host" }, "args": "__PUBLIC_HOST__" }
      ]
    },
    {
      "src": "__BASE_PATH__/_ferndesk",
      "dest": "https://__FERNDESK_HOST____BASE_PATH__/_ferndesk",
      "transforms": [
        { "type": "request.headers", "op": "set", "target": { "key": "x-ferndesk-base-path" }, "args": "__BASE_PATH__" },
        { "type": "request.headers", "op": "set", "target": { "key": "x-forwarded-host" }, "args": "__PUBLIC_HOST__" },
        { "type": "request.headers", "op": "set", "target": { "key": "x-ferndesk-original-host" }, "args": "__PUBLIC_HOST__" }
      ]
    },
    {
      "src": "__BASE_PATH__/_ferndesk/(.*)",
      "dest": "https://__FERNDESK_HOST____BASE_PATH__/_ferndesk/$1",
      "transforms": [
        { "type": "request.headers", "op": "set", "target": { "key": "x-ferndesk-base-path" }, "args": "__BASE_PATH__" },
        { "type": "request.headers", "op": "set", "target": { "key": "x-forwarded-host" }, "args": "__PUBLIC_HOST__" },
        { "type": "request.headers", "op": "set", "target": { "key": "x-ferndesk-original-host" }, "args": "__PUBLIC_HOST__" }
      ]
    },
    {
      "src": "__BASE_PATH__",
      "dest": "https://__FERNDESK_HOST__/",
      "transforms": [
        { "type": "request.headers", "op": "set", "target": { "key": "x-ferndesk-base-path" }, "args": "__BASE_PATH__" },
        { "type": "request.headers", "op": "set", "target": { "key": "x-forwarded-host" }, "args": "__PUBLIC_HOST__" },
        { "type": "request.headers", "op": "set", "target": { "key": "x-ferndesk-original-host" }, "args": "__PUBLIC_HOST__" }
      ]
    },
    {
      "src": "__BASE_PATH__/(.*)",
      "dest": "https://__FERNDESK_HOST__/$1",
      "transforms": [
        { "type": "request.headers", "op": "set", "target": { "key": "x-ferndesk-base-path" }, "args": "__BASE_PATH__" },
        { "type": "request.headers", "op": "set", "target": { "key": "x-forwarded-host" }, "args": "__PUBLIC_HOST__" },
        { "type": "request.headers", "op": "set", "target": { "key": "x-ferndesk-original-host" }, "args": "__PUBLIC_HOST__" }
      ]
    }
  ]
}

Deploy your project

Commitez et poussez vos modifications pour déclencher un nouveau déploiement Vercel. La nouvelle configuration de routage prendra effet une fois le déploiement terminé.

La section headers désactive la mise en cache des réécritures de Vercel sur les chemins Ferndesk. Cela empêche la mise en cache de réponses Not found obsolètes lorsque des ressources ou des pages Ferndesk sont demandées avant que le proxy ne soit entièrement configuré.

Étape 3 : Vérifier la configuration

Testez que votre centre d'aide est désormais accessible via le chemin de votre sous-dossier personnalisé.

Open your subfolder URL

Accédez à https://yourdomain.com/help (ou au chemin du sous-dossier que vous avez choisi) dans votre navigateur.

Check that the help center loads

Vous devriez voir votre centre d'aide Ferndesk avec votre image de marque et votre contenu.

Test navigation and assets

Parcourez quelques articles pour confirmer que la navigation fonctionne. Vérifiez que le style, les images et le JavaScript se chargent correctement.

Si votre centre d'aide se charge avec une navigation et un style fonctionnels, le proxy inverse est correctement configuré. Vos clients peuvent désormais accéder à votre centre d'aide via le chemin de votre sous-dossier personnalisé.

Dépannage

Problème	Cause	Solution
Erreur 404 Not Found	Routes non configurées ou déploiement non terminé	Vérifiez que `vercel.json` se trouve à la racine de votre projet et que le déploiement est terminé. Vérifiez que tous les espaces réservés ont été remplacés par des valeurs réelles.
Page blanche ou style cassé	L'hôte Ferndesk ou le chemin de base est incorrect	Vérifiez que `FERNDESK_HOST` correspond à l'hôte de votre tableau de bord Ferndesk et que `BASE_PATH` correspond exactement à votre sous-dossier configuré.
Les ressources ou le CSS ne se chargent pas après la configuration initiale	Vercel a mis en cache une réponse obsolète	Redéployez votre projet Vercel pour vider les réponses mises en cache. La configuration des `headers` devrait empêcher cela pour les requêtes futures.
Le centre d'aide fonctionne mais le nom d'hôte ne correspond pas	Mauvais hôte public dans les routes	Assurez-vous que `PUBLIC_HOST` est votre nom d'hôte de production (par exemple, `www.example.com`), et non une URL de prévisualisation Vercel.

Un problème est survenu ? Contactez-nous à l'adresse [email protected] et nous vous aiderons à terminer votre configuration.

Supprimer le sous-dossier

Pour arrêter d'utiliser le sous-dossier personnalisé et revenir à votre URL Ferndesk par défaut :

Remove the domain in Ferndesk

Dans Ferndesk, allez dans Help Center → Customize → Custom domain et cliquez sur Remove Domain.

Remove the Vercel routes

Supprimez ou commentez les entrées headers et routes liées à Ferndesk dans votre fichier vercel.json, puis redéployez.

Prochaines étapes

Cela vous a-t-il été utile ?