Información sobre GitHub Docs estructura del sitio
El GitHub Docs sitio era originalmente una aplicación web ruby on Rails. En algún momento posterior se convirtió en un sitio estático impulsado por Jekyll. Unos años después se migró a Nanoc, otro generador de sitios estáticos de Ruby.
Hoy en día es un servidor web dinámico de Node.js basado en Express, que utiliza middleware para gestionar redirecciones HTTP adecuadas, la detección de la cabecera de idioma y la generación dinámica de contenido para dar soporte a las distintas variantes de la documentación de 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
datadirectorio están disponibles para las plantillas a través de la{% data %}etiqueta . - Los archivos Markdown pueden contener texto preliminar.
- Se admite el comportamiento del complemento de Jekyll
redirect_from.
Configuración del entorno local
Puede clonar el GitHub Docs repositorio y ejecutar la aplicación localmente en el equipo, después de alguna configuración inicial.
Instalación de Node.js
El GitHub Docs sitio tiene 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, descargue el instalador "LTS" de nodejs.org. Para comprobar qué versión de Node necesita, puede ver el package.json archivo en el GitHub Docs repositorio. 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 local GitHub Docs
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 local, visita localhost:4000 en el explorador.
Cuando estés listo para detener el servidor local, escribe Ctrl+C en la ventana del terminal.
Nota:
Normalmente, solo debes ejecutar npm ci y npm run build cada vez que incorpores la versión más reciente de una rama.
*
npm ci realiza una instalación limpia de las dependencias, sin actualizar el archivo package-lock.json.
*
npm run build crea 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 GitHub Docs aplicación, consulte Solución de problemas de su ambiente en el repositorio de github/docs.
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.
Nota:
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.ts.
Usar GitHub Codespaces
Como alternativa a la ejecución GitHub Docs local, puede usar GitHub Codespaces. GitHub Codespaces le permite editar, obtener una vista previa y probar los cambios directamente desde el explorador.
Para obtener más información sobre cómo usar un codespace para trabajar en la documentación de GitHub, consulte Trabajando en la documentación de GitHub en un codespace.