Publica tu documentación en una subcarpeta con Vercel
Sigue esta guía para alojar tu centro de ayuda de Ferndesk en una subcarpeta personalizada (como yourdomain.com/help) mediante el proxy de origen externo de Vercel.
Esto tarda aproximadamente 10 minutos y requiere un proyecto de Vercel en el que puedas añadir un archivo de configuración vercel.json.
¿Tienes problemas? Ponte en contacto con [email protected] y te ayudaremos a completar la configuración.
Requisitos previos
Un espacio de trabajo de Ferndesk con acceso de administrador
Un proyecto de Vercel que sirva tu sitio web principal
Acceso para añadir un archivo
vercel.jsona la raíz de tu proyecto
La configuración de una subcarpeta personalizada requiere tener un método de pago activo registrado.
Paso 1: Configura la subcarpeta en Ferndesk
Primero, configura tu centro de ayuda de Ferndesk para que use una ruta de subcarpeta personalizada.
Abre la configuración del centro de ayuda
Inicia sesión en tu espacio de trabajo de Ferndesk, despliega Centro de ayuda en la barra lateral izquierda y haz clic en Personalizar.
Selecciona Subcarpeta personalizada
Haz clic en Dominio personalizado.
Selecciona la opción Subcarpeta personalizada.
Introduce tu dominio y subcarpeta
Introduce tu dominio en el campo Dominio (por ejemplo, www.example.com) y, a continuación, introduce la ruta de subcarpeta que desees en el campo Ruta (por ejemplo, /help o /docs).
Guarda y copia el host de Ferndesk
Haz clic en Configurar subdirectorio. Una vez configurado, copia el host proxy de Ferndesk (por ejemplo, acme.hc.ferndesk.com); lo necesitarás para la configuración de Vercel.
Usa el nombre de host exacto de producción de Vercel (por ejemplo, www.example.com), no el nombre de host de una implementación de vista previa. Si el nombre de host cambia después de la primera implementación, es posible que persistan entradas obsoletas de la caché.
Paso 2: Añade la configuración de enrutamiento de Vercel
Crea o actualiza vercel.json en la raíz de tu proyecto para enviar las solicitudes a Ferndesk mediante un proxy. Esta configuración utiliza las routes de Vercel con transformaciones de encabezados de solicitud para enviar a Ferndesk la ruta base y la información del host necesarias.
Crea o abre vercel.json
Si aún no tienes un archivo vercel.json en la raíz de tu proyecto, créalo. Si ya lo tienes, ábrelo para editarlo.
Añade la configuración
Pega la configuración siguiente en tu archivo vercel.json. Reemplaza los marcadores de posición con tus valores reales:
PUBLIC_HOST — el nombre de host de producción de Vercel (por ejemplo,
www.example.com)FERNDESK_HOST — el host de Ferndesk que copiaste del panel de Ferndesk (por ejemplo,
acme.hc.ferndesk.com)BASE_PATH — la ruta de tu subcarpeta, incluida la barra inicial (por ejemplo,
/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?__bp=__BASE_PATH__",
"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?__bp=__BASE_PATH__",
"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?__bp=__BASE_PATH__",
"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__/_ferndesk/$1?__bp=__BASE_PATH__",
"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__/?__bp=__BASE_PATH__",
"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?__bp=__BASE_PATH__",
"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__" }
]
}
]
}El parámetro __bp permite a Ferndesk servir tus páginas de ayuda desde su caché perimetral, por lo que se cargan en mucho menos de un segundo en todo el mundo.
Implementa tu proyecto
Confirma y sube tus cambios para activar una nueva implementación de Vercel. La nueva configuración de enrutamiento tendrá efecto cuando finalice la implementación.
La sección headers desactiva el almacenamiento en caché de reescrituras de Vercel en las rutas de Ferndesk. Esto evita que se almacenen en caché respuestas obsoletas de Not found cuando se solicitan recursos o páginas de Ferndesk antes de que el proxy esté completamente configurado.
Paso 3: Verifica la configuración
Comprueba que tu centro de ayuda ya esté disponible en la ruta de subcarpeta personalizada.
Abre la URL de tu subcarpeta
Accede a https://yourdomain.com/help (o a la ruta de subcarpeta que hayas elegido) en tu navegador.
Comprueba que se cargue el centro de ayuda
Deberías ver tu centro de ayuda de Ferndesk con tu marca y contenido.
Prueba la navegación y los recursos
Abre varios artículos para confirmar que la navegación funciona. Comprueba que los estilos, las imágenes y JavaScript se carguen correctamente.
Si tu centro de ayuda se carga con la navegación y los estilos funcionando, el proxy inverso está configurado correctamente. Tus clientes ya pueden acceder a tu centro de ayuda en la ruta de subcarpeta personalizada.
Solución de problemas
Problema | Causa | Solución |
|---|---|---|
Error 404 Not Found | Las rutas no están configuradas o la implementación no ha terminado | Verifica que |
Página en blanco o estilos dañados | El host de Ferndesk o la ruta base son incorrectos | Comprueba que |
Los recursos o el CSS no se cargan después de la configuración inicial | Vercel almacenó en caché una respuesta obsoleta | Vuelve a implementar tu proyecto de Vercel para borrar las respuestas almacenadas en caché. La configuración de |
El centro de ayuda funciona, pero el nombre de host no coincide | El host público en las rutas es incorrecto | Asegúrate de que |
¿Algo salió mal? Ponte en contacto con nosotros en [email protected] y te ayudaremos a completar la configuración.
Eliminar la subcarpeta
Para dejar de usar la subcarpeta personalizada y volver a tu URL predeterminada de Ferndesk:
Elimina el dominio en Ferndesk
En Ferndesk, ve a Centro de ayuda → Personalizar → Dominio personalizado y haz clic en Eliminar subdirectorio.
Elimina las rutas de Vercel
Elimina o comenta las entradas headers y routes relacionadas con Ferndesk de tu archivo vercel.json y, a continuación, vuelve a implementar el proyecto.