Logo

Fredy Rosero's Blog

5 December 2021

Github Page con StackEdit

tags: GitHub, - Jekyll, - Stackedit

Primero debemos entender como funciona Github Pages (en adelante, GHP). GHP utiliza Jekyll el cual compila sitios web a a partir de Markdown (en adelante, MD).

Workspace

Debemos configurar un espacio de trabajo, donde vamos a guardar nuestros documentos (en formato markdown) y plantillas Stackedit, por tanto, debe ser en un repositorio diferente al de Github username/username.github.io donde queremos publicar, ya que tendríamos un enredo de markdowns stackedit y jekyll del mismo nombre.

Formato

Debemos entender que el formato en que GHP reconoce las páginas es el siguiente

---
[Encabezados YAML]
---
[Markdown]

Por tal motivo necesitamos crear un plantilla, en mi caso llamada “Github pages” con la siguiente entrada:

---  
{{{files.0.content.yamlProperties}}}  
---  
{{{files.0.content.text}}}

[2]

Los valores content.yamlProperties son las metada del archivo (File properties) en formato YAML. El valor content.text simplemente entrega tal cual esta nuestro documento markdown de Stackedit.

Jekyll diferencia su cotenido entre pages y posts puesto que esta orientado a Blogging. Los posts tiene la particularidad de ser nombrados con la sintáxis YEAR-MONTH-DAY-title.MARKUP y ubicados en /_posts/. Además tienen metada imporante para una renderización efectiva como date , categories y tags. Así un MD para GHP nombrado ‘2021-12-05-Welcome-to-Jekyll’ se vería así:

---
layout: post
title: "Welcome to Jekyll!"
date: 2021-12-05 03:13:22 -0500
categories: jekyll update
---
# Hi!
You’ll find this post in your `_posts` directory.

Metadata

Los metadatos tittle, date , categories y tags están presentes en File properties > Simple properties, mas no layout, por tal motivo, necesitamos definirlo en File properties > YAML properties. El parámetro layout define la plantilla de _layouts del tema escogido con la cual vamos a renderizar. Debemos tener en cuenta que no todos lo temas de Jekyll para GHP tienen el layout post, en caso de utlizar un tema sin este layout simlpemenet nos sale la págine en blanco.

Publish

En nuestro repositorio GHP creado, habremos definido la carpeta y rama de publicación, las cuales van a ser nuestros parámetros de publicación. Primero en publish, autorizamos Stackedit en Github pero con una pequeña pirueta para solventar el error HTTP 400. Luego en publish seleccionamos “Publish to Github” y definimos los siguientes parámetros:

Renderizar ecuaciones

Stackedit utiliza KaTeX para renderizar expresiones LaTeX de manera automática:

La función Gamma satisface $\Gamma(n) = (n-1)!\quad\forall n\in\mathbb N$ por medio dela integral de Euler \(\Gamma(z) = \int_0^\infty t^{z-1}e^{-t}dt\,.\)

Pero Github desafortunadamente no renderiza la expresiones anterior ni soporta fórmulas matemáticas como la siguiente [3] a diferencia de GitLab

e^{i \pi} = -1

Imágen GFM

Sin embargo, podemos utilizar APIs que reciban el contenido LaTeX como variable GET y que devuelan una imagen, y así insertar la imagen en el MD como elemento img HTML:

<img src="https://render.githubusercontent.com/render/math?math=e^{i \pi} = -1">

Si queremos utilizar la sintaxis de imagen GFM (GitHub Flavored Markdown) [4] necesitamos codificar en URL UTF-8 el contenido LaTeX o de lo contrario tendremos problemas de renderización en Stackedit y directamente en Github https://github.com/username/username.github.io.git sin embargo no en GHP https://username.github.io.git

![e^{i \pi} = -1](https://render.githubusercontent.com/render/math?math=e^{i \pi} = -1)

e^{i \pi} = -1

Podemo utilizar herramientas en linea como [urlencoder.org] para codificarel texo correctamente (https://www.urlencoder.org/enc/latex/)

![e^{i \pi} = -1](https://render.githubusercontent.com/render/math?math=e%5E%7Bi%20%5Cpi%7D%20%3D%20-1)

e^{i \pi} = -1

Podemos utilizar un código sencillo para generar nuestras imágenes GFM a partir de LaTeX

Ejemplo

La función Gamma satisface por medio dela integral de Euler

UML diagrams

You can render UML diagrams using Mermaid. For example, this will produce a sequence diagram:

sequenceDiagram
Alice ->> Bob: Hello Bob, how are you?
Bob-->>John: How about you John?
Bob--x Alice: I am good thanks!
Bob-x John: I am good thanks!
Note right of John: Bob thinks a long<br/>long time, so long<br/>that the text does<br/>not fit on a row.

Bob-->Alice: Checking with John...
Alice->John: Yes... John, how are you?

And this will produce a flow chart:

graph LR
A[Square Rect] -- Link text --> B((Circle))
A --> C(Round Rect)
B --> D{Rhombus}
C --> D

Fuentes

Written with StackEdit.

También te puede interesar