Visualización de tu README del Proyecto en Orbit

La pestaña Docs renderiza el README de tu repositorio dentro de KPanel, para que la documentación del proyecto esté a un clic de sus implementaciones en lugar de en una pestaña del navegador que alguien tiene que ir a buscar.

Dónde está la pestaña Docs

Abre Orbit, haz clic en el proyecto y elige Docs bajo el grupo Overview en la barra de pestañas del proyecto.

No hay nada que configurar. Si el proyecto tiene un repositorio conectado con un README en su raíz, la pestaña lo renderiza.

Qué archivo se muestra

Orbit obtiene el README de la rama por defecto del repositorio conectado.

En GitHub intenta varios nombres convencionales en orden: README.md, readme.md, README.MD, README e readme.txt, tomando el primero que existe. En GitLab y Bitbucket busca README.md.

Solo se comprueba la raíz del repositorio. Un README dentro de un subdirectorio, incluyendo el directorio raíz de una aplicación monorepo, no se detecta.

Qué se renderiza

El README se renderiza como markdown: encabezados, listas, tablas, enlaces, código en línea y bloques de código delimitados se muestran como era de esperar.

Las rutas de imagen relativas dentro de un README apuntan al repositorio, no a KPanel, por lo que las imágenes que funcionan en el sitio del proveedor pueden no resolverse aquí. Si una imagen es importante, usa una URL absoluta.

Estados vacíos

Dos estados reemplazan el contenido cuando no hay nada que mostrar:

• No repository connected, con un botón Connect repository. Conecta uno primero: ver Connecting a GitHub Repository, Connecting a GitLab Repository o Connecting a Bitbucket Repository.
• No README found, pidiéndote que añadas un README.md a la raíz de tu repositorio, con un enlace para crear uno en tu proveedor.

Ambos enlazan al proveedor para que puedas actuar de inmediato, y la vista poblada tiene un enlace View on al archivo en sí para cuando quieras editarlo.

Escribir un README que valga la pena renderizar

Porque esta pestaña está junto al historial de implementaciones, el README más útil para un proyecto de Orbit es uno operacional. Alguien lo abre porque acaba de recibir el proyecto y necesita cambiar algo de forma segura.

Una estructura que funciona:

What this is. Un párrafo. Qué hace el proyecto y a quién sirve.

Running it locally. Los comandos exactos, incluyendo el gestor de paquetes. pnpm install && pnpm dev supera a un párrafo describiendo lo mismo.

Environment variables. Cuáles existen y para qué sirve cada una. Nunca los valores: esos pertenecen a las variables de entorno del proyecto, no a un archivo en el repositorio. Ver Environment Variables in Orbit.

How it deploys. Qué rama es producción, si los tags se implementan y qué gates están vigentes. Apunta a la pestaña Orbit Deployment Pipeline en lugar de duplicarla, porque la pestaña no puede quedar obsoleta y tu README sí.

How to roll back. Dos frases y un enlace a Rolling Back a Deployment. Esta es la cosa que la gente necesita en su peor momento, y debe estar donde la buscarán.

Who owns it. Un equipo o una persona. Los proyectos perduran más que la gente que los configura.

Añadiendo un distintivo de estado en directo

Como el README se renderiza aquí y en tu proveedor, vale la pena añadir un distintivo de estado de implementación. Orbit publica uno para cada proyecto.

Abre Settings y busca la tarjeta Status badge. Muestra una vista previa en directo y tres botones de copiar: la URL del distintivo, un fragmento de markdown y un fragmento HTML. Pega el markdown en la parte superior de tu README.

El distintivo es un SVG pequeño que informa del estado actual del entorno de producción del proyecto: deployed, building, failed, queued o no deployments. No necesita autenticación, por lo que se renderiza para cualquiera que lea el repositorio, y enlaza de vuelta al proyecto en KPanel.

Eso te da un README que muestra, de un vistazo, si la producción es actualmente saludable. Es la línea de más valor que puedes añadirle.

Mantenerlo honesto

Un README que describe una configuración que el proyecto ya no tiene es peor que ningún README, porque la gente confía en él. Dos hábitos lo mantienen preciso:

• Link rather than duplicate. Cualquier cosa que sea visible en KPanel, como configuración de construcción, gates y configuración de entorno, debe enlazarse, no replantearse.
• Update it in the same pull request. Si un cambio altera cómo se ejecuta el proyecto, el cambio de README pertenece a ese pull request, no a una limpieza posterior.

Solución de problemas

The tab shows an old version. El caché de cinco minutos. Espera y recarga.

No README found, but there is one. Comprueba que está en la raíz del repositorio y se llama README.md. En GitLab y Bitbucket el nombre tiene que coincidir exactamente.

The repository is connected but the tab says it is not. La conexión puede haber perdido acceso, por ejemplo si la integración fue eliminada en el lado del proveedor. Reconéctala desde la configuración del proyecto.

Images do not load. Las rutas relativas no se resuelven aquí. Usa URLs absolutas.

The badge shows no deployments. El entorno de producción nunca ha tenido una implementación exitosa. Implementa una vez y se actualiza.

Dónde ir después

• Orbit Deployment Pipeline, la versión en directo de lo que un README normalmente intenta describir.
• Orbit Project Settings para el distintivo de estado y el resto de la configuración.
• Environment Variables in Orbit para los valores que un README nunca debe contener.