Etiquetas HEAD personalizadas

⭐
Available in Pro Projects

Aplica JavaScript, estilos, enlaces y metadatos a todo el proyecto, que se añaden a la etiqueta HEAD de la página.

Personalizar las etiquetas HEAD

Para personalizar las etiquetas HEAD:

  • Abre Project Settings → Customisation.

  • En la tarjeta Custom code, haz clic en Edit HEAD tags.

  • Introduce las etiquetas personalizadas como lo harías en HTML y luego haz clic en Save draft en el menú superior. Esto guarda el HTML en modo borrador, para que puedas probarlo.

  • Para publicarlo para los lectores, haz clic en Save & publish.

  • Para descartar los cambios del borrador, haz clic en Revert.

Todas las etiquetas personalizadas solo se ejecutarán en modo en vivo y no se cargarán en el modo editor.

Etiquetas HEAD de la organización

Si tus proyectos pertenecen a una organización, el propietario puede mantener un único conjunto de etiquetas HEAD compartido entre ellos desde Configuración de la organización → Custom HEAD tags.

Un proyecto no las hereda automáticamente. Para activarlas, abre Project Settings → Customisation y activa Use organisation HEAD tags. Las etiquetas de la organización se insertan antes que las propias del proyecto, así que, cuando ambas definen lo mismo, prevalece la del proyecto.

Uso de un agente de programación con IA

Un agente de programación con IA como Claude Code, Cursor o Codex puede escribir el JavaScript por ti. Copia el siguiente prompt en tu agente y rellena las tres líneas del principio.

El prompt hace que el agente lea las páginas relevantes antes de escribir nada: Personalización de elementos visuales para comprobar si algún ajuste ya resuelve el caso, esta página, CSS personalizado, Herramientas para desarrolladores y Personalizaciones populares. Para cualquier otra cosa, parte del llms.txt de este sitio.

I want to customise my DeveloperHub docs with Custom CSS or Custom HEAD tags (JavaScript).

What I want: <describe the change>
My docs URL: <https://docs.example.com>
My UI: <Matcha, Next or Original>

Before writing any code, read these pages:
- https://docs.developerhub.io/support-center/customising-visuals.md (built-in settings that need no code)
- https://docs.developerhub.io/support-center/custom-css.md (Custom CSS rules and CSS variables)
- https://docs.developerhub.io/support-center/custom-javascript.md (Custom HEAD tags rules and events)
- https://docs.developerhub.io/support-center/developer-tools.md (functions, events and objects available to scripts)
- https://docs.developerhub.io/support-center/css-customisations.md (worked examples)
To look up anything else, start from https://docs.developerhub.io/llms.txt.

Then:
1. If a built-in setting already does what I want, tell me which one and stop.
2. Use Custom CSS wherever CSS can do it. Use Custom HEAD tags only for what needs JavaScript.
¿Sin acceso a la web?

Si tu agente no puede abrir páginas web, abre tú mismo cada enlace del prompt y pega el contenido después del prompt.

Pega las etiquetas que devuelva en Custom HEAD tags y pruébalas con Save draft antes de publicar. Si algo falla, desactiva las etiquetas HEAD en tu navegador para comprobar si son la causa.

Formato de las etiquetas

Las etiquetas deben añadirse completas, tal como existirían en HEAD, por ejemplo:

<!-- Script to install jquery -->
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.3.1/jquery.min.js"></script>

<!-- Install Bootstrap CSS -->
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.4.1/css/bootstrap.min.css">

<!-- Add your own CSS - You can also do that through Custom CSS -->
<style>
.my-container{
width: 100%;
}
</style>

<!-- Add meta such as OpenGraph title -->
<meta property="og:title" content="X Documentation">

No añadas <body>, <html> ni otras etiquetas que no existan de forma natural en HEAD.

Advertencia

No uses async ni defer en tus scripts. Los scripts se cargarán de forma asíncrona de todos modos.

JavaScript compatible

Los scripts se ejecutan exactamente como los escribes; no los compilamos. Usa solo JavaScript que ejecuten nuestros navegadores compatibles.

Cada script se ejecuta por separado

Los scripts en línea no pueden usar import, export ni await de nivel superior. Para cargar una biblioteca, añádela con <script src="...">. Las declaraciones let, const y class de nivel superior permanecen dentro de su propia etiqueta <script>, así que, para compartir algo entre etiquetas, asígnalo a window.

¿Por qué añadir scripts?

Al añadir scripts, puedes hacer más con tu documentación:

  • Instalar servicios de terceros para el seguimiento, el análisis y la interacción con tus lectores.

  • Crear scripts que interactúen con Custom HTML en las páginas o con Página de inicio personalizada.

  • Añadir reglas de redirección en JavaScript.

  • Añadir tu propio conjunto de iconos mediante CSS.

  • Mejorar tu SEO añadiendo las etiquetas META relevantes para tu negocio.

  • Cambiar el texto de la interfaz.

Hooks externos

Hay varios eventos disparados por DeveloperHub que pueden ayudarte a lograr el nivel de personalización que necesitas. La lista completa de hooks está disponible en Javascript Dispatched Events.

Proyecto cargado

Para detectar cuándo se carga un proyecto, que es también cuando se cargan la mayoría de los elementos de la página, puedes escuchar un evento personalizado en document llamado onprojectloaded. Un ejemplo:

<script>
document.addEventListener('onprojectloaded', function () {
const topnav = document.querySelector(".topnav"); // .topnav is loaded at this time, probably not before this.
topnav.classList.add('wide');
});
</script>

Si quieres modificar la navegación superior, debes usar este evento.

Usa `onprojectloaded` en lugar de `document.onload`.

Como DeveloperHub es una aplicación de una sola página, document.onload no tiene efecto en las etiquetas HEAD personalizadas. Todas las etiquetas HEAD personalizadas se cargan después de que se llama a document.onload. Usa onprojectloaded siempre que necesites usar document.onload.

Cambios de sección

Para detectar cuándo cambia una sección (página de inicio, documentación), puedes escuchar un evento personalizado en document llamado onsectionchange. Un ejemplo:

<script>
document.addEventListener('onsectionchange', function (event) {
switch (event.detail.type) {
case 'landing-page':
// It is a landing page
break;
case 'documentation':
// It is a documentation
break;
case 'reference':
// It is a reference
break;
}
});
</script>

Si la sección que cambió es una documentación, también se indican los índices.

Cambios de página

Para detectar cuándo cambia una página, puedes escuchar un evento personalizado en document llamado onpagechange. Un ejemplo:

<script>
document.addEventListener('onpagechange', function (event) {
console.log(event.detail.slug); // e.g. getting-started
});
</script>

Reglas de redirección

Con JS personalizado, puedes configurar reglas de redirección en el front-end. Por ejemplo, si quieres redirigir uno de tus proyectos cuyo versionado semántico es inferior a 1.0 a otro, podrías usar algo como esto:

<script>
const redirectDocs = function() {
const regex = /^\/([0-9\.]+)\//i;
const path = window.location.pathname;
if ((match = regex.exec(path))) {
const redirectPath = match[0];
const version = match[1];
const semver = version.split('.');
if (semver[0] < 1) {
window.location.href = "https://alpha.always-blue.io"+redirectPath;
}
}
}

redirectDocs();
</script>

O, si has cambiado el slug de una documentación, quizá quieras redirigir al nuevo slug:

<script>
const redirectDocs = function() {
const oldDoc = "/old-doc-slug";
const newDoc = "/new-doc-slug";
const path = window.location.pathname;
if (path.includes(oldDoc)) {
window.location.pathname = path.replace(oldDoc, newDoc);
}
}
redirectDocs();
</script>

Si necesitas reglas de redirección más potentes, consulta las reglas de redirección 301 en el servidor.

Página de inicio personalizada cargada

Consulta Página de inicio personalizada.

Probar las etiquetas HEAD

Las etiquetas HEAD no se ejecutan en el editor, así que prueba un borrador en tu documentación publicada:

  1. Edita las etiquetas HEAD y luego haz clic en Save draft en el menú superior. Los lectores siguen recibiendo las etiquetas publicadas.

  2. Haz clic en See draft project en el aviso situado sobre las etiquetas. Tu documentación se abre con las etiquetas del borrador en ejecución, enmarcada en azul, con un dock en la parte inferior que lista los borradores que estás viendo.

  3. Cuando todo funcione, haz clic en Save & publish.

La documentación que abras desde el editor sigue ejecutando tus borradores de este modo. Para ver una página como la ven los lectores, haz clic en View as Reader en el dock, o abre la documentación en una ventana de incógnito.

Desactivar las etiquetas HEAD

Para comprobar si un script o estilo de las etiquetas HEAD está causando problemas, puede que quieras desactivar momentáneamente todas las etiquetas HEAD solo en tu navegador. Para ello, añade el parámetro de consulta ?disableScripts=true a cualquier URL de la documentación publicada.

Por ejemplo, si tu documentación está disponible en https://example.com/docs, puedes desactivar las etiquetas HEAD durante tu sesión usando https://example.com/docs?disableScripts=true.

Cuando recargues la página sin disableScripts=true, las etiquetas HEAD volverán a estar activadas.

customisation
  Última actualización