Docusaurus es un proyecto de código abierto desarrollado por Facebook para ayudar a los desarrolladores a crear y mantener sitios web basados en documentación para ZEIT Now, GitHub Pages, Netlify y Render. Fue construido usando reaccionar y admite el formato de archivo Markdown y más de 60 idiomas también.
Indice
- Instalar Docusaurus
- Crear un repositorio en GitHub
- Generar el código de documentación con Docusaurus Insertar
- archivos en GitHub
- Crear una página de GitHub
- Probar nuestro sitio
Instalar Docusaurus
Docusaurus está disponible como un paquete NPM, así como un paquete de hilo. Como se recomienda en la documentación, utilizaremos hilo para instalarlo. Use el siguiente comando para instalar Docusaurus.
yarn global add docusaurus-init
Si no tiene hilo instalado en su computadora, use primero el siguiente comando
Instalación para Windows usando Chocolatey
choco install yarn
Instalación para Mac usando Homebrew
brew install yarn
Instalación para Linux
sudo apt-get install yarn
Si prefiere instalar Docusaurus a nivel mundial, ejecute yarn global add docusaurus-init o npm install --global docusaurus-init . Después de eso, corre docusaurus-init .
Crear un repositorio en GitHub
Haga clic en este enlace para navegar a GitHub ( github.com) y crear un nuevo repositorio.
Generando el código de documentación con Docusaurus
Nota: Cree una carpeta de proyecto antes de continuar y abra la nueva carpeta en VSCode
Pegue el siguiente comando para permitir que Docusaurus genere el código repetitivo.
docusaurus-init
Una vez que se haya completado, Docusaurus habría agregado un par de carpetas junto con los archivos relacionados con Docker y un archivo .gitignore
Trabajaremos principalmente con los documentos y la carpeta del sitio web.
Punto final del sitio
En la carpeta "sitio web", haga clic en el archivo siteConfig.js para cambiar la URL.
De forma predeterminada, Docusaurus lo llevará a https://misubdominio-o-dominio.anezsoft.com para cambiarlo a la URL de su página de GitHub.
La URL debe cambiarse en el objeto siteConfig. Cambie los valores de la siguiente manera.
url: 'https://github.com/<Github username> .github.io'
baseUrl: '/ <nombre del repositorio> /'
En mi caso
Puede cambiar el nombre de la organización a lo que quiera. Se encuentra bajo el mismo objeto siteConfig.
Generando el sitio web estático
Una vez que haya completado los cambios anteriores, vaya al archivo del sitio web en la terminal y ejecute el siguiente comando.
yarn run build
Una vez hecho esto, se genera el sitio web estático y se crean 2 carpetas nuevas, a saber, build e i18n.
Empujando archivos a GitHub
Ahora que se ha creado el sitio estático, debemos llevarlo a GitHub y crear una página de GitHub para él, ya que le proporcionamos un github.io como punto final.
La forma de hacerlo es tener todos los archivos de origen en una rama y los archivos relacionados con el sitio web en otra.
Comando Git para ser ejecutado ...
Cree un repositorio vacío en la raíz de la carpeta del proyecto
git init
Agregar control remoto
git remote add <alias> <url remota de github>
Agregar y confirmar los archivos de origen
git add.
git commit -m "<mensaje de confirmación>"
empujando archivos fuente a GitHub
Enviaré todos los archivos de origen a la rama maestra, siéntase libre de usar cualquier otro
git push <alias> master
Empujando el código de nuestro sitio web de documentación ...
Como dije anteriormente, el código relacionado con el sitio web debe estar en una nueva rama, creemos una nueva rama llamada gh-pages y empujemos allí solo los archivos relacionados con el sitio web.
Nombra la rama como "gh-pages". Esto se seleccionará automáticamente como una rama para las páginas de GitHub. GitHub no elige ramas con ninguna otra rama excepto la rama maestra de lo contrario.
Comando Git para ser ejecutado ...
Crear una nueva sucursal
git checkout -b gh-pages
Agregar solo un archivo
git add -f sitio web / build / test-site
Como esta carpeta está presente en el archivo .gitignore, necesitamos usar el indicador -f para forzar la inserción
Cometer el cambio
git commit -m "<mensaje de confirmación>"
Empujando archivos
git subtree push --prefix website / build / test-site origin gh-pages
Usamos este comando para permitir que Git inserte solo los archivos presentes en la carpeta "sitio web / compilación / sitio de prueba" y no todo el árbol.
Crear una página de GitHub
Navegue a su repositorio y haga clic en configuración
Al desplazarse hacia abajo a la sección de páginas de Github, debe notar que GitHub ha seleccionado automáticamente la rama "gh-pages" en cuanto a la página y también nos ha proporcionado un punto final de URL.
Probar nuestro sitio
Haga clic en la URL en la sección de la página de GitHub
Comentarios