Bloques sincronizados

Los bloques sincronizados te permiten crear un único contenido (fuente única) que se puede reutilizar en varias páginas tantas veces como sea necesario. Cuando modificas un bloque sincronizado, los cambios se reflejan automáticamente en todas las páginas donde se utiliza el bloque, lo que garantiza coherencia y eficiencia en la gestión de tu contenido.

Reutilizar contenido: creación de bloques sincronizados

Para crear un bloque sincronizado:

  • Escribe / en una línea nueva o haz clic en a la izquierda de cualquier línea.

  • Elige Bloque sincronizado . Se abre el cuadro de diálogo Elegir un bloque sincronizado.

  • Haz clic en Crear . Aparecerá un formulario, con el contenido a la izquierda y los detalles del bloque en un panel a la derecha.

  • En el formulario, debes definir:

    • El contenido: Usa el editor para redactar el contenido del bloque sincronizado. Este contenido es flexible y se puede modificar más adelante. Puedes incluir cualquiera de los bloques que ya son compatibles con DeveloperHub.

    • Título: Elige un título que represente con precisión el contenido y que facilite a tus compañeros localizarlo. Ten en cuenta que el título es editable y se puede cambiar más adelante.

    • ID: Un identificador del bloque sincronizado. Se rellena a partir del título mientras escribes y puedes cambiarlo hasta que guardes. Una vez guardado, el ID no se puede modificar. Este ID será visible en tus exportaciones. Por ejemplo, si estás creando una guía sobre cómo instalar Docker, tu ID podría ser docker-installation.

    • Variables (opcional): Palabras que cada instancia del bloque puede definir por sí misma, como el nombre de un producto o una versión. Consulta Variables en bloques sincronizados.


Reutilizar un bloque sincronizado

Para reutilizar un bloque sincronizado:

  • Escribe / en una línea nueva o haz clic en a la izquierda de cualquier línea.

  • Elige Bloque sincronizado . Se abre el cuadro de diálogo Elegir un bloque sincronizado.

  • Selecciona el bloque sincronizado que quieres reutilizar, o búscalo primero. Su contenido se muestra en una vista previa a la derecha.

  • Haz clic en Elegir.


Identificar un bloque sincronizado

Cuando estás en el editor, un bloque sincronizado aparece delimitado por un borde discontinuo y con la etiqueta Bloque sincronizado: seguida de su título, para que veas exactamente qué contenido le pertenece. Al pasar el cursor por encima aparece una barra de herramientas en la esquina superior derecha con Editar y Reemplazar . Si el bloque tiene variables, la barra de herramientas también incluye Variables , y la etiqueta indica cuántos valores ha cambiado esa instancia.


Editar un bloque sincronizado

Modificar un bloque sincronizado cambia su contenido en todas las instancias donde se usa. Esta operación solo pueden realizarla los publicadores.

Para editar un bloque sincronizado:

  • Ve a una página que tenga el bloque sincronizado que quieres editar.

  • Pasa el cursor sobre el bloque sincronizado y haz clic en Editar en la barra de herramientas de su esquina superior derecha.

  • Aparecerá un formulario donde puedes modificar el título, el contenido y las variables.

  • Realiza los cambios y haz clic en Guardar.

El pie del formulario indica cuántas páginas usan el bloque, para que sepas hasta dónde llega un cambio antes de guardarlo.

Para cambiar un bloque sincronizado por otro distinto, haz clic en Reemplazar y elige otro bloque.

Variables en bloques sincronizados

Las variables permiten que un mismo bloque sincronizado se lea de forma distinta en cada página. Por ejemplo, un bloque de instalación puede nombrar una herramienta diferente en cada página que lo use, mientras los pasos siguen siendo los mismos. El bloque define un valor predeterminado para cada variable y cada instancia del bloque puede dar el suyo, de modo que el mismo bloque usado dos veces en una página puede leerse de forma distinta en cada lugar.

Añadir una variable

  • Abre el formulario del bloque, ya sea al crear un bloque o al editar uno.

  • En el panel de la derecha, en Variables, haz clic en Añadir variable.

  • Ponle un nombre a la variable, como tool, y opcionalmente un valor predeterminado, como Acme CLI. Un nombre empieza con una letra, tiene al menos dos caracteres y usa solo letras, números y guiones bajos.

  • Coloca la variable en el contenido. Escribe % y selecciónala en Variables de bloque, o escribe / y elige Variable de bloque. Se muestra como una etiqueta, y al señalarla se resalta su variable en el panel.

  • En el código, escribe el nombre entre signos de porcentaje, como %version%.

  • Haz clic en Guardar.

Ahora todas las páginas que usan el bloque muestran el valor predeterminado dondequiera que se haya colocado la variable.

Definir valores en una página

  • Pasa el cursor sobre el bloque sincronizado en la página y haz clic en Variables en su barra de herramientas.

  • Escribe un valor para cada variable que quieras cambiar. Cada campo vacío muestra el valor predeterminado, y un campo que se deja vacío sigue mostrándolo.

Los valores pertenecen a la página, por lo que se guardan, se redactan como borrador y se publican con la página como cualquier otro cambio. Cambiar un valor predeterminado en el bloque actualiza de inmediato todas las páginas que no definen su propio valor, porque los bloques sincronizados no tienen borradores.

Conviene saber

  • El nombre de una variable no se puede cambiar una vez guardado el bloque, igual que el ID del bloque. Para renombrar una, añade una variable nueva, traslada sus usos a ella y luego elimina la antigua.

  • Eliminar una variable que el contenido todavía usa deja esos lugares vacíos, por lo que el panel te avisa antes y muestra en cuántos lugares se usa. En un bloque de código, su %name% se muestra tal como se escribió o, si existe, como la variable de proyecto con ese nombre.

  • Una variable con el mismo nombre que una variable de proyecto se apropia de ese nombre dentro del código del bloque, de modo que %version% ahí significa la variable del bloque. El panel lo indica cuando ocurre. Fuera del bloque, la variable de proyecto no cambia.

  • Un valor puede contener una variable de proyecto, como %latest_version%, en un valor predeterminado o en el valor de una página. Se muestra el valor de esa variable de proyecto.

  • Los anclajes de los encabezados siguen a los valores. Un encabezado del bloque que contiene una variable toma su anclaje de enlace del valor mostrado en esa página. Así, el mismo encabezado puede tener un anclaje distinto en cada página, y cambiar un valor, o un valor predeterminado que usan las páginas, cambia el anclaje y rompe los enlaces que apuntan al anterior.

  • Los valores no se traducen. Una página traducida muestra los mismos valores que su página de origen, así que mantén en el contenido del bloque las palabras que necesiten traducción.

  • Las variables personalizadas de los lectores no cambian las variables de bloque. La personalización solo rellena variables de proyecto.

Eliminar/archivar un bloque sincronizado

Una vez que un bloque sincronizado se añade a tu proyecto, nunca se puede eliminar, pero sí archivar. Archivar un bloque sincronizado no elimina sus instancias de ninguna página donde se haya añadido, solo lo quita de la lista de bloques sincronizados que tus compañeros pueden elegir.

Para archivar un bloque sincronizado:

  • Escribe / en una línea nueva o haz clic en a la izquierda de cualquier línea.

  • Elige Bloque sincronizado . Se abre el cuadro de diálogo Elegir un bloque sincronizado.

  • Busca el bloque sincronizado que quieres archivar y pulsa el icono que aparece junto a él.

  • Confirma tu elección.

Edición en un repositorio sincronizado

Si tu proyecto usa Sincronización con GitHub, tus bloques sincronizados se replican en el repositorio bajo _synced-blocks/, un archivo por bloque, con el nombre del ID del bloque. Puedes escribir y revisar un bloque allí como cualquier otro cambio, y los bloques que edites en el editor se confirman de vuelta. Consulta Bloques sincronizados para ver la estructura de archivos y el frontmatter, incluido cómo un bloque declara sus variables y cómo una página define sus propios valores.

Puedes enlazar a páginas dentro de un bloque sincronizado. Sin embargo, su uso tiene limitaciones.

Limitación de los enlaces de página

Cuando el bloque sincronizado se usa en una versión distinta de aquella en la que se creó, se enlaza mediante el slug de la página. Cambiar el slug de la página en la versión de origen o en la de destino romperá el enlace, y se te notificará al ver una página que tenga el bloque sincronizado.

Por ejemplo: si creaste un bloque sincronizado que enlaza a la página "Contact Us" en v1.0 con el slug "contact-us", luego usaste el bloque sincronizado en v2.0 y más tarde cambiaste el slug de la página Contact Us a "how-to-contact-us", el enlace de la página se romperá en v2.0. Tendrías que crear un bloque sincronizado aparte para v2.0 para resolver esta situación.


blocks
  Última actualización