​
Introduction

El editor web es una interfaz visual para crear, editar y revisar documentación directamente en tu navegador.

El editor web ofrece una experiencia What-You-See-Is-What-You-Get (WYSIWYG) mientras mantiene la sincronización con tu repositorio Git, lo que te permite ver actualizaciones en tiempo real y colaborar con tu equipo en los cambios de la documentación.

​
Editor web vs. CLI

El editor web te permite escribir y editar tu documentación en tu navegador sin necesidad de herramientas de desarrollo locales o usar la línea de comandos. Deberías usar el editor web si quieres mantener tu documentación en un solo lugar con una sola herramienta.

La CLI es una herramienta de línea de comandos que te permite crear y gestionar tu documentación localmente usando el IDE de tu elección. Deberías usar la CLI si quieres integrar la documentación en tu flujo de trabajo de desarrollo existente.

Tanto el editor web como la CLI están completamente integrados con tu repositorio Git, por lo que puedes usarlos indistintamente y diferentes miembros de tu equipo pueden usar cualquiera de las herramientas según sus preferencias.

​
Modos del Editor

El editor web ofrece dos modos para adaptarse a diferentes preferencias y necesidades de edición.

Puedes cambiar entre los modos naturales en cualquier momento usando el interruptor en la esquina superior derecha de la barra de herramientas del editor.

​
Modo Visual

El modo visual proporciona una experiencia WYSIWYG donde los cambios que haces en el editor son los cambios que se publicarán en tu sitio de documentación. Este modo es ideal cuando quieres ver cómo se verán tus cambios en tiempo real.

​
Menú de Componentes

Puedes agregar bloques de contenido y otros componentes a tu documentación en el modo visual usando el menú desplegable de componentes.

  1. Presiona la tecla / para abrir el menú de componentes.
  2. Selecciona un componente del menú.

​
Modo Markdown

El modo Markdown proporciona acceso directo al código MDX subyacente de tu documentación. Este modo es preferible cuando necesitas un control preciso sobre las propiedades de los componentes o cuando prefieres escribir en sintaxis Markdown/MDX.

​
Realizando Cambios

  1. Navegar por archivos: Usa el explorador de archivos de la barra lateral para navegar por tu documentación.
  2. Abrir un archivo: Haz clic en el archivo que quieres editar para abrirlo en el editor.
  3. Realizar cambios: Edita el contenido usando el modo visual o Markdown. Los cambios se guardan automáticamente como borradores.
  4. Vista previa de cambios: Ve cómo se verán tus cambios en el modo visual.

​
Publicación

La publicación actualiza directamente tu rama de despliegue configurada. Para flujos de trabajo colaborativos, considera usar ramas y solicitudes de extracción en su lugar.

Cuando estés listo para hacer que tus cambios estén en vivo, haz clic en el botón Publish en la esquina superior derecha del editor web.

Tus cambios se desplegarán en tu sitio de producción inmediatamente.

​
Branches

Las ramas te permiten trabajar en cambios de documentación sin actualizar la versión principal hasta que estés listo para que tus cambios se publiquen.

Usa ramas para actualizaciones significativas, nuevas secciones o cuando varios miembros del equipo están trabajando en diferentes partes de la documentación simultáneamente.

​
Creando una Rama

  1. Selecciona el nombre de la rama en la barra de herramientas del editor (generalmente main por defecto).
  2. Selecciona New Branch.
  3. Ingresa un nombre descriptivo para tu rama.
  4. Selecciona Create Branch.

​
Cambiando de Rama

  1. Selecciona el nombre de la rama actual en la barra de herramientas del editor.
  2. Selecciona la rama a la que quieres cambiar del menú desplegable.

​
Guardando Cambios en una Rama

Para guardar tus cambios en una rama, selecciona el botón Save Changes en la esquina superior derecha del editor.

Cuando estás trabajando en una rama, tus cambios no se guardan automáticamente.

​
Pull Requests

Las pull requests (o PRs) te permiten a ti y a otras personas revisar los cambios que has realizado en una rama y luego fusionar esos cambios en tu documentación principal.

​
Creando una Pull Request en una Rama

  1. Realiza tus cambios en una rama.
  2. Haz clic en el Publish Pull Request botón en la esquina superior derecha del editor.
  3. Añade un Título y Descripción de Pull Request para tu pull request. Un buen título y descripción ayudará a los revisores a entender los cambios que has realizado.
  4. Haz clic en Publish Pull Request.

​
Revisando Pull Requests

Puedes revisar pull requests en tu plataforma Git (GitHub, GitLab).

Después de crear una pull request, puedes ver una implementación de vista previa de los cambios.

Después de que un revisor apruebe una pull request, puedes fusionar la pull request en tu rama principal y los cambios se implementarán en tu sitio de documentación en vivo.

​
Sincronización Git

El editor web se integra con tu repositorio Git, asegurando que todos los cambios estén correctamente versionados y rastreados.

​
Cómo funciona la sincronización Git

  • Autenticación: El editor web se conecta a tu repositorio Git a través de nuestra GitHub App o GitLab integration.

  • Obtención automática: Cuando abres el editor, automáticamente obtiene el contenido más reciente de la rama principal de tu repositorio.

  • Seguimiento de cambios: A medida que realizas ediciones, el editor web rastrea los cambios y puede confirmarlos en tu repositorio.

  • Ramificación: Puedes hacer cambios directamente en tu rama principal o en una rama separada, dependiendo de tus preferencias de flujo de trabajo.

  • Pull requests: Para flujos de trabajo colaborativos, puedes crear pull requests desde el editor web.

​
Terminología Git

Entender los siguientes términos puede ayudarte a trabajar más eficazmente con el editor web y el flujo de trabajo Git.

​
Solución de problemas

Aquí hay soluciones a problemas comunes que podrías encontrar con el editor web.