MkDocs: Generador de sitios Web (GitHub pages)

Instalación

Es necesario tener Python instalado previamente y el gestor de paquetes pip. Si es la primera vez que instalas pip debes bajar get-pip.py y ejecutarlo:

python get-pip.py

A continuación instalamos mkdocs en Win:

python -m pip install mkdocs

Creación inicial del proyecto

Creamos una carpeta que albergará nuestro proyecto y desde la carpeta padre ejecutamos:

python -m mkdocs new nombre_carpeta_proyecto

Ahora dentro de la carpeta ya tenemos los archivos necesarios:

  • mkdocs.yml
  • docs/index.md

MkDocs incorpora también un servidor para visualizar la Web a medida que la generamos, dentro de la carpeta del proyecto lanzamos el siguiente comando:

python -m mkdocs serve

Ahora podemos visualizar la Web en la siguiente dirección: http://127.0.0.1:8000/.

Configuración del proyecto

Editamos el fichero mkdocs.yml para cambiar el nombre del sitio.

Añadiendo páginas

Añadimos nuevos archivos MarkDown dentro de la carpeta docs, por ejemplo about.md. Ahora en la barra superior tendremos dos elementos de menú apuntando a cada página y botones para navegar entre ellas.

 

Definiendo el theme

Modificamos el archivo mkdocs.yml:

 

Cambiando el icono Favicon

creamos una carpeta img dentro de docs y guardamos nuestro icono como favicon.ico

Generando la Web

Dentro de la carpeta del proyecto ejecutamos:

python -m mkdocs build

Esto crea una subdirectorio site con la Web traducida a HTML.

GitHub pages

Ejecutamos:

mkdocs gh-deploy

El comando genera los archivos de la Web y usa ghp-import  para hacer actualizar el repositorio GitHub (nos solicitará los datos de nuestra cuenta GitHub).

Configuramos GitHub.

Ahora ya puedo ver la Web en el siguiente enlace.

 

 

 

Anuncios

GitHub Pages: API REST JSON estática

GitHub: static-rest-json-api.

Llamadas ejemplo:

GitHub Pages no sólo vale para albergar sitios Web. Podemos usarlo para crear un servidor REST con datos estáticos JSON (o cualquier otro formato de texto plano como CSV).  Vamos a guardar en el mismo proyecto el cliente que realice consultas en JS (de lectura sólo claro) y los ficheros JSON con la base de datos.

Lo único que hay que hacer es crear un nuevo proyecto y en las opciones de configuración convertirlo en una página Web.

Lo siguiente es crear un fichero de ejemplo, users.json.

 

Ya podemos observar el resultado de la llamada con este enlace.

Si queremos analizar con más detalle la llamada podemos usar la aplicación Postman para Chrome.

Ahora implementamos un cliente básico de consulta users_get_test.html:

Ejecutamos el test en el navegador y observamos el resultado en la consola:

Enlaces externos

GitHub: Minimal Mistakes theme

Me ha gustado el theme “Minimal Mistakes” (Jekyll theme gem ) para generar un sitio con información de un proyecto.

Posts relacionados:

Instalando el theme

Para alojarlo en GitHub Pages debemos hacer un fork del repositorio original (crea una copia exactamente igual del original) se puede usar este enlace para hacer un fork del theme o directamente copiar todos los ficheros descargándolos.

Ya tengo creada una copia en mi GitHub del theme haciendo un fork.

Recomendación: Borrar las carpetas /docs y /test.

Ahora para convertirlo en una página de GitHub vamos a la configuración del repositorio (“Settings”), aprovechamos para cambiar el nombre del repositorio. La página se carga del contenido dentro de la carpeta “/docs”.

Ahora ya podemos ver la nueva página:

Configuración

Los parámetros de configuración globales que afectan a toda la Web se pueden encontrar en el fichero en el raíz _config.yml  (fichero de configuración Jekyll).

Modificamos la información de la página (title, name, description, url, baseurl, repository), parámetros de redes sociales como Twitter.

Skin

Podemos cambiar el esquema de colores del theme seleccionando entre los disponibles:

minimal_mistakes_skin : "default" # "air", "contrast", "dark", "dirt", "mint", "sunrise"

Nota: Podemos personalizar los estilos modificando /assets/css/main.scss 

Cambiando el idioma

El contenido de texto para los elementos gráficos del interface de usuario están agrupados en _data/ui-text.yml.

Podemos modificar el idioma en _config.yml con el parámetro “locale”.

locale : "es"

Navegación

Para definir los títulos de enlaces y la URL destino debemos modificar  ‘_data/navigation.yml‘ (dentro de carpeta docs).

 

Los nuevos elementos se posicionaran de forma horizontal en forma de menú.

Posts

Las entradas se almacenan en la carpeta “_posts/“, podemos habilitar el menú de acceso a las entradas en “_data/navigation.yml” para que se muestre una lista de las entradas ordenadas por fecha.

Los enlaces se la sección “docs” se encuentran más abajo dentro de navigation.yml

 

Dentro de la carpeta “_posts” cada entrada es un fichero Markdown con la fecha en el nombre:

Para saber algo más sobre la estructura de las entradas podemos consultar la entrada de Jekyll sobre posts.

Vamos a consultar que aspecto tiene este post con título “Layout: Header Video“:

Editamos el fichero “_posts/2017-01-23-layout-header-video.md“:

El post debería mostrar un vídeo en la cabecera.

Un post básico debería contener como mínimo una cabecera con estos campos:

Vamos a crear un post nuevo “_posts/2017-10-08-mi-primer-post.md“:

 

Los campos entre “—” son la cabecera del documento. Añadimos un título, las categorías permiten agrupar los posts relacionados, por ejemplo los relacionados con “Post Formats“. Algo similar hacemos con las etiquetas que comparten los posts.

Para consultar diferentes formatos de posts con vídeos, galerías de fotos y otros contenidos podemos revisar cada post de ejemplo uno por uno.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

GitHub Pages: Webs estáticas para nuestros proyectos como un repositorio más

El famoso gestor de versiones de código fuente GitHub ofrece otra funcionalidad no tan conocida. Con GitHub Pages podemos crear portales Web estáticos para documentar un proyecto (sin apenas conocimiento de HTML y de forma rápida), o un perfil profesional por ejemplo como carta de presentación.  Las Webs funcionan igual que cualquier otro repositorio de código fuente (operaciones push, commit… desde nuestra computadora local) y se editan en texto plano en un fichero con sintaxis Markdown.

En lo que se refiere al aspecto visual no destaca mucho (tampoco creo que sea el propósito), GitHub ofrece una serie de themes limitados.

Este ejemplo es de una página con el theme Leap day  aplicado por ejemplo:

Como funciona

Vamos a empezar creando una página con uno de los themes disponibles en pocos minutos. Creamos un nuevo repositorio en nuestra cuenta de GitHubUna vez creado vamos a las opciones de configuración (“Settings”), dentro encontramos el apartado “GitHub Pages”:

Seleccionamos un Theme:

Ya hemos creado nuestra primera página (con contenidos de ejemplo). Podemos editar la página editando el archivo README.md desde GitHub.

En mi caso el resultado es el siguiente: https://ikerlandajuela.github.io/Windows-Presentation-Foundation/

El proyecto solo contiene dos ficheros: README.md (con el contenido de la página) y _config.yml.

_config.yml es un archivo especial donde se define el theme Jekyll Midnight.

Enlaces externos