Acerca de la estructura del sitio de GitHub Docs
El sitio de GitHub Docs era originalmente una aplicación web de Ruby on Rails. En algún momento posterior se convirtió en un sitio estático con tecnología de Jekyll. Unos años después se migró a Nanoc, otro generador de sitios estáticos de Ruby.
Actualmente es un servidor web de Node.js dinámico con tecnología de Express, que usa middleware para admitir redireccionamientos HTTP adecuados, la detección de encabezados de idioma y la generación de contenido dinámico para admitir los distintos tipos de documentación del producto de GitHub, como Free, Pro y Team y GitHub Enterprise Server.
Las herramientas de este sitio han cambiado a lo largo de los años, pero muchas de las convenciones de creación probadas del sitio de Jekyll original se han conservado.
- El contenido se escribe en archivos Markdown, que residen en el directorio
content.
- Los archivos del directorio
dataestán disponibles para las plantillas a través de la etiqueta{% data %}. - Los archivos Markdown pueden contener texto preliminar.
- Se admite el comportamiento del complemento de Jekyll
redirect_from.
Configuración del entorno local
Puedes clonar el repositorio de GitHub Docs y ejecutar la aplicación localmente en el equipo, después de una instalación inicial.
Instalación de Node.js
El sitio de GitHub Docs cuenta con tecnología de Node.js. Se ejecuta en entornos de macOS, Windows y Linux.
Para ejecutar el sitio, necesitará Node.js. Para instalar Node.js, descarga el instalador "LTS" desde nodejs.org. Para comprobar qué versión de Node necesitas, puedes ver el archivo package.json en el repositorio de GitHub Docs. La versión de Node aparece en el campo engine, similar al ejemplo siguiente, que indica que puedes usar la versión principal 16 de Node o la versión principal 18 de Node.
"engines": {
"node": "^16 || ^18"
}
Si usas nodenv, consulta los documentos nodenv para obtener instrucciones sobre cómo cambiar las versiones de Node.js.
Inicio de un servidor de GitHub Docs local
Una vez que hayas instalado Node.js (que incluye el popular administrador de paquetes npm), abre el terminal y ejecuta los siguientes comandos.
git clone https://github.com/github/docs
cd docs
npm ci
npm start
Ahora debes tener un servidor en ejecución. Para acceder al entorno de versión preliminar local, visita localhost:4000 en el explorador.
Cuando estés listo para detener el servidor local, escribe Ctrl+C en la ventana del terminal.
Note
Normalmente, solo debes ejecutar npm ci y npm run build cada vez que incorpores la versión más reciente de una rama.
npm cirealiza una instalación limpia de las dependencias, sin actualizar el archivopackage-lock.json.npm run buildcrea recursos estáticos, como archivos JavaScript y CSS.
Si desea obtener más información sobre la depuración y la solución de problemas de la aplicación GitHub Docs, consulta Solución de problemas de su ambiente en el repositorio github/docs.
Uso de accesos directos del explorador
El directorio src/bookmarklets del repositorio de GitHub Docs contiene accesos directos del explorador que pueden ayudar a revisar la documentación de GitHub. Para más información, consulta el archivo README del directorio.
Habilitación de diferentes idiomas
De forma predeterminada, el servidor local no se ejecuta con todos los idiomas admitidos habilitados. Si necesitas ejecutar un servidor local con un idioma determinado, puedes editar temporalmente el script start en package.json y actualizar la variable ENABLED_LANGUAGES.
Por ejemplo, para habilitar japonés y portugués, además de inglés, puedes editar package.json y establecer ENABLED_LANGUAGES='en,ja,pt' en el script start. A continuación, reinicia el servidor para que el cambio surta efecto.
Note
Antes de confirmar los cambios, debes revertir el archivo package.json a su estado original.
Los códigos de idioma admitidos se definen en src/languages/lib/languages.js.
Uso de GitHub Codespaces
Como alternativa a la ejecución de GitHub Docs de forma local, puedes usar GitHub Codespaces. GitHub Codespaces te permite editar, previsualizar y probar los cambios directamente desde el explorador.
Para obtener más información sobre el uso de un codespace para trabajar en la documentación de GitHub, consulta Trabajo en GitHub Docs en un codespace.