Sobre este pequeño post, documentaremos como instalar la herramienta de visualización de contenido y documentación llamada GitBook, esta herramienta utiliza tecnologías modernas como Node.js para construir libros o documentos usando GitHub/Git y el lenguaje de demarcado Markdown.

Herramientas

  • PC de desarrollo con Ubuntu 16.04

Instalando NodeJS

antes de instalar GitBook, lo primero que debemos hacer es instalar NodeJS ya que por medio de NPM podremos instalar la herramienta.

instalamos curl y con esta herramienta descargaremos para despues procesar el script que ejecutaremos via bash

$ sudo apt install curl

Descargamos y ejecutamos el script que procedera a actualizar el repositorio del sistema dependiendo de su version.

$ curl -sL https://deb.nodesource.com/setup_8.x | sudo -E bash -



#Salida del sistema
## Confirming "xenial" is supported...

+ curl -sLf -o /dev/null 'https://deb.nodesource.com/node_8.x/dists/xenial/Release'

## Adding the NodeSource signing key to your keyring...

+ curl -s https://deb.nodesource.com/gpgkey/nodesource.gpg.key | apt-key add -
OK

## Creating apt sources list file for the NodeSource Node.js 8.x LTS Carbon repo...

+ echo 'deb https://deb.nodesource.com/node_8.x xenial main' > /etc/apt/sources.list.d/nodesource.list
+ echo 'deb-src https://deb.nodesource.com/node_8.x xenial main' >> /etc/apt/sources.list.d/nodesource.list

## Running `apt-get update` for you...

+ apt-get update
Hit:1 http://co.archive.ubuntu.com/ubuntu xenial InRelease
Hit:2 http://co.archive.ubuntu.com/ubuntu xenial-updates InRelease                                                                   
Hit:3 http://co.archive.ubuntu.com/ubuntu xenial-backports InRelease                                                        
Hit:4 http://packages.osrfoundation.org/gazebo/ubuntu-stable xenial InRelease                 
Hit:5 http://security.ubuntu.com/ubuntu xenial-security InRelease       
Get:6 https://deb.nodesource.com/node_8.x xenial InRelease [4.646 B]
Get:7 https://deb.nodesource.com/node_8.x xenial/main Sources [761 B]
Get:8 https://deb.nodesource.com/node_8.x xenial/main amd64 Packages [1.007 B]
Get:9 https://deb.nodesource.com/node_8.x xenial/main i386 Packages [1.007 B]
Fetched 7.421 B in 1s (4.494 B/s)     
Reading package lists... Done

## Run `sudo apt-get install -y nodejs` to install Node.js 8.x LTS Carbon and npm
## You may also need development tools to build native addons:
     sudo apt-get install gcc g++ make
## To install the Yarn package manager, run:
     curl -sL https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add -
     echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list
     sudo apt-get update && sudo apt-get install yarn

Si al finalizar la ejecucion del script evidenciamos que la distribucion es soportada y que los repositorios han sido correctamente actualizados, podremos instalar nodejs instalando al tiempo npm.

$ sudo apt-get install -y nodejs


#Salida del sistema
Reading package lists... Done
Building dependency tree       
Reading state information... Done
The following package was automatically installed and is no longer required:
  libuv1
Use 'sudo apt autoremove' to remove it.
The following NEW packages will be installed:
  nodejs
0 upgraded, 1 newly installed, 0 to remove and 0 not upgraded.
Need to get 12,7 MB of archives.
After this operation, 61,4 MB of additional disk space will be used.
Get:1 https://deb.nodesource.com/node_8.x xenial/main amd64 nodejs amd64 8.11.3-1nodesource1 [12,7 MB]
Fetched 12,7 MB in 37s (340 kB/s)                                                                                                                                                                                                     
Selecting previously unselected package nodejs.
(Reading database ... 255423 files and directories currently installed.)
Preparing to unpack .../nodejs_8.11.3-1nodesource1_amd64.deb ...
Unpacking nodejs (8.11.3-1nodesource1) ...
Processing triggers for man-db (2.7.5-1) ...
Setting up nodejs (8.11.3-1nodesource1) ..

Instalando GitBook.

si la instalaciòn de NodeJs ha sido correcta, procedemos a intalar GitBook vìa NPM

$ sudo npm install gitbook-cli -g


#Salida del comando
npm audit` to get more info.
/usr/bin/gitbook -> /usr/lib/node_modules/gitbook-cli/bin/gitbook.js
+ gitbook-cli@2.3.2
added 578 packages in 38.683s

Hola Libro :)

Para comprobar que la herramienta funciona adecuadamente vamos a crear un nuevo libro y lo serviremos desde la aplicación para comprobar que habilita correctamente el socket HTTP y podamos ver el libro desde nuestro navegador Web.

  • Creamos nuestro directorio para el nuevo libro digital y accedemos a este, en este caso llamaremos "MiBook" a nuestro nuevo libro.
$ mkdir MiBook && cd MiBook
  • Dentro del directorio le indicamos a GitBook que vamos a iniciar un nuevo libro.
$ gitbook init


#Salida del sistema
warn: no summary file in this book 
info: create README.md 
info: create SUMMARY.md 
info: initialization is finished 
  • Una vez creado el libro podremos servirlo para proximamente visualizarlo localmente desde el computador.
$ gitbook serve


#Salida del sistema
Live reload server started on port: 35729
Press CTRL+C to quit ...

info: 7 plugins are installed 
info: loading plugin "livereload"... OK 
info: loading plugin "highlight"... OK 
info: loading plugin "search"... OK 
info: loading plugin "lunr"... OK 
info: loading plugin "sharing"... OK 
info: loading plugin "fontsettings"... OK 
info: loading plugin "theme-default"... OK 
info: found 1 pages 
info: found 0 asset files 
info: >> generation finished with success in 0.8s ! 

Starting server ...
Serving book on http://localhost:4000
  • Accedemos al equipo localmente por medio del navegador indicando el puerto que ha servidor la aplicacion y de inmediatamente visualizamos la pagina web que pertenece al libro nuevo diseñado.
Hola Libro
  • Servido el libro y comprobado que esta correcto despues de editarlo y agregarle su contenido, podremos compilarlo, crear y exportar el libro en formato HTML para proximanete desplegarlo sobre un servidor WEB, para ello utilizamos el comando "build" disponible en GitBook.
$ gitbook build


#Salida del sistema
info: 7 plugins are installed 
info: 6 explicitly listed 
info: loading plugin "highlight"... OK 
info: loading plugin "search"... OK 
info: loading plugin "lunr"... OK 
info: loading plugin "sharing"... OK 
info: loading plugin "fontsettings"... OK 
info: loading plugin "theme-default"... OK 
info: found 1 pages 
info: found 0 asset files 
info: >> generation finished with success in 0.5s ! 

Realizada la compilación del libro podremos ver que en el directorio actual se genera un subdirectorio llamado "_book" donde en el se encontrara el contenido web que podremos desplegar en el servidor.

$ ls -l


#Salida del sistema
total 12
drwxrwxr-x 3 heberth heberth 4096 ago 11 10:20 _book
-rw-rw-r-- 1 heberth heberth   16 ago 11 10:12 README.md
-rw-rw-r-- 1 heberth heberth   40 ago 11 10:12 SUMMARY.md
$ cd _book/ && ls -l


#Salida del sistema
total 16
drwxrwxr-x 9 heberth heberth 4096 ago 11 10:20 gitbook
-rw-rw-r-- 1 heberth heberth 6045 ago 11 10:20 index.html
-rw-rw-r-- 1 heberth heberth  568 ago 11 10:20 search_index.json

Referencias:
https://nodejs.org/es/download/package-manager/#distribuciones-de-linux-basadas-en-debian-y-ubuntu
https://toolchain.gitbook.com/setup.html
https://github.com/GitbookIO/gitbook