Hosting su sottopercorso
Ospita la documentazione in un sottopercorso del dominio, come yoursite.com/docs, con configurazioni per Vercel, CloudFront, Cloudflare e proxy inversi.
Ospita la documentazione in un sottopercorso del dominio invece che in un sottodominio separato: yoursite.com/docs per impostazione predefinita o un segmento personalizzato come yoursite.com/help. Per tutte le opzioni di deploy, consulta Panoramica del deploy.
Gli screenshot mostrano l'interfaccia in inglese.
Perché usare un sottopercorso?
Rispetto a un sottodominio come docs.yoursite.com, un sottopercorso mantiene i lettori sul dominio principale e le pagine della documentazione contribuiscono all'autorevolezza del dominio nei motori di ricerca, invece di distribuire i segnali di ranking tra due host.
Come funziona
Il server web o il CDN inoltra le richieste da /docs/* al tuo sito Jamdesk, mantenendo l'URL originale nel browser:
Il proxy inoltra l'intestazione X-Jamdesk-Forwarded-Host con il tuo dominio. Jamdesk la usa per:
- Verificare che il tuo dominio sia autorizzato a distribuire i contenuti
- Applicare la tua configurazione dal dashboard
In questo modo, la configurazione del proxy deve essere eseguita una sola volta: se modifichi le impostazioni nel dashboard, non è necessario aggiornare il proxy.
Configurazione per provider
Scegli il tuo provider di hosting per iniziare:
Prerequisiti
Prima di configurare il proxy:
- Aggiungi il tuo dominio nel dashboard di Jamdesk, in Settings → Custom Domain
- Attiva "Host at a subpath"
- Scegli il tuo sottopercorso (facoltativo; consulta Scelta del sottopercorso di seguito) e fai clic su Save
Il tuo sottodominio Jamdesk (ad esempio acme.jamdesk.app) verrà visualizzato nel dashboard. Ti servirà per configurare il proxy.
Il salvataggio di una modifica all'hosting su sottopercorso (attivazione o disattivazione, oppure modifica del sottopercorso) avvia una ricostruzione completa della documentazione. È necessario perché la struttura degli URL cambia (ad esempio, tra /introduction e /docs/introduction).
Scelta del sottopercorso
Per impostazione predefinita, la documentazione viene distribuita in /docs. Per usare un percorso diverso, come /help o /support, inseriscilo nel campo del sottopercorso accanto all'interruttore. Quando il campo è vuoto, l'interruttore mostra Host at a subpath (e.g. /docs); inserendo un valore, il testo si aggiorna in tempo reale mostrando il percorso che stai per attivare (Host at /help e così via).
Il campo accetta un singolo segmento in lettere minuscole: solo lettere, cifre e trattini interni, senza trattini iniziali o finali, con un massimo di 63 caratteri. Alcuni segmenti sono riservati e vengono rifiutati direttamente, tra cui api, jd, percorsi amministrativi comuni come wp-admin e qualsiasi codice locale che la documentazione potrebbe usare (fr, es, de e simili). In questo modo il sottopercorso non può mai entrare in conflitto con un percorso già gestito da Jamdesk.
Lascia vuoto il campo per mantenere il valore predefinito /docs.
Rinominare o rimuovere il sottopercorso
Modificare il sottopercorso o cancellarlo per tornare al valore predefinito è sicuro e non interrompe i link già indicizzati o aggiunti ai segnalibri:
/docscontinua sempre a essere disponibile. Anche dopo il passaggio a un sottopercorso personalizzato come/help, i percorsi originali/docs/*continuano a rispondere sul sottodominio[slug].jamdesk.appe attraverso qualsiasi proxy che li utilizzi ancora. I link canonici passano immediatamente al nuovo sottopercorso, così i motori di ricerca possono indicizzarlo nuovamente. Nulla di ciò che punta già a/docssi interrompe: puoi quindi aggiornare la configurazione del proxy con i tuoi tempi, senza pressione.- La rinomina di un sottopercorso personalizzato inoltra quello precedente, per una sola rinomina. Se rinomini
/helpin/guide, le richieste a/help/*vengono reindirizzate con codice 308 al percorso corrispondente/guide/*. Questa cronologia ha un solo livello: se rinomini di nuovo/guidein/support,/guide/*viene reindirizzato a/support/*, ma/help/*(il segmento di due rinomine precedenti) non viene più tracciato. Di conseguenza, quei link smettono di risolversi e portano a una pagina "not found", talvolta dopo un reindirizzamento a un percorso combinato insolito. Non concatenare le rinomine se conti sul reindirizzamento per mantenere attivi i vecchi link; aggiorna invece i link esterni al sottopercorso attuale. - Il ripristino di
/docsfunziona allo stesso modo: il sottopercorso personalizzato precedente (un solo livello di cronologia) viene reindirizzato a/docs/*.
Questo non significa che /docs venga reindirizzato al sottopercorso scelto. Non è necessario, perché /docs continua a essere disponibile direttamente e in modo permanente. Il reindirizzamento a un solo livello si applica esclusivamente al sottopercorso personalizzato che stai abbandonando.
Dopo aver configurato il proxy, esegui un test visitando https://yoursite.com/docs (o il sottopercorso configurato). La documentazione dovrebbe caricarsi con tutti gli asset e i link funzionanti correttamente.
Devo nascondere il sottodominio jamdesk.app?
No. Il tuo sottodominio [slug].jamdesk.app rimane raggiungibile (è l'origine upstream a cui inoltra il proxy), ma non entrerà in concorrenza con il tuo sito nei risultati di ricerca:
- Quando il tuo dominio è registrato, ogni pagina distribuita direttamente dal sottodominio include un link canonico che punta alla stessa pagina sul tuo dominio, così i motori di ricerca consolidano tutti i segnali di ranking su quest'ultimo.
- Prima della registrazione di un dominio, le pagine del sottodominio in modalità sottopercorso vengono contrassegnate come
noindex, quindi non entrano mai nell'indice.
Se vuoi anche impedire l'accesso ai contenuti dal sottodominio (non solo escluderli dall'indice), attiva la Protezione tramite password: il sottodominio mostrerà una schermata di sblocco al posto della documentazione.