L2: Markdown y Github Wiki - myTeachingURJC/Mecatronica GitHub Wiki
- Tiempo: 2h
-
Objetivos de la sesión:
- Familiarzarse con el formato Markdown
- Manejo de la wiki de github
- ¡Practicar!
- Introducción
- Repositorios de trabajo
- Parte I: Introducción a los lenguajes de marcado
- Parte II: Markdown
- Parte III: Actividades guiadas
- ¡A practicar!
- Resumen de tareas a realizar
- Conclusiones
- Autores
- Licencia
- Enlaces
En esta sesión aprenderemos a manejar la Wiki de Github usando el lenguaje de marcado Markdown
Usaremos la wiki con dos propósitos:
- La creación de tu Bitácora personal: Es con la que se evaluará tu trabajo personal en la asignatura, junto con el repositorio
- Documentación del proyecto en grupo
En la asignatura trabajaremos con dos repositorios: Un repositorio personal (uno por estudiante) y un repositorio del proyecto (uno por grupo de trabajo). Ambos serán públicos
Cada estudiante, a título individual, deberá crear un repositorio personal llamado Mecatronica-2024-2025. Este repositorio será público, y en él se irán subiendo todos los archivos relativos a las pruebas/experimentos que cada uno realiza para aprender o practicar
En este repositorio se debe crear una wiki que alojará la bitácora de trabajo personal de cada uno: dibujos, diseños, ... en general la evolución personal dentro de la asignatura. Las bitácoras son documentos personales y por tanto el lenguaje puede ser coloquial y poco preciso. Dan una idea cómo has ido evolucionando en la asignatura: qué cosas estás aprendiendo, qué diseños estás haciendo, qué errores has cometido y cómo los has solucionado. Todo esto a título personal
El objeto de esta bitácora, además de servir de documentación, es la de practicar el uso de las wiki y el Markdown. ¡La única manera de aprender es practicando!
El proyecto de mecatrónica lo realizarás con tu grupo de trabajo en un repositorio público de Github. Primero debéis elegir a un representante de vuestro grupo de trabajo
-
El representante de cada grupo deberá crear el repositorio: Mecatronica-Proyecto. En ese repositorio se almacenarán todos los ficheros del proyecto (dibujos, imágenes, archivos 3D, código...)
-
El representante del grupo deberá dar permisos de escritura en ese repositorio a todos los miembros de su grupo de trabajo, para que puedan hacer sus commits directamente (Los miembros también pueden hacer un fork y emitir pull-request, pero es más rápido y fácil si envían directamente los commits)
-
La memoria del proyecto se realizará en formato markdown en la wiki del proyecto
-
El representante deberá crear la wiki, y dar permisos al resto de miembros de su grupo para editarla
-
En la página principal de la wiki deberá figurar también la información de todos los miembros del grupo, con los enlaces a sus cuentas de github
Antes de empezar con el lenguaje markdown vamos a presentar su contexto, y tener una idea más precisa del ecosistema de los lenguajes de marcado
Para describir o explicar un proyecto en ingeniería utilizamos un lenguaje humano, como por ejemplo el Español (pero podría ser también el Inglés). Usando este lenguaje podemos escribir un documento técnico
Imaginemos que estamos escribiendo un documento técnico para describir nuestro último robot. Este es uno de los fragmentos:
Observamos varias cosas:
- El documento tiene una estructura. Tiene un apartado, numerado como 1, y dentro hay un sub-apartado, denotado por 1.1 y a su vez, dentro de este hay un párrafo
- Hay palabras especiales, que se han resaltado frente a otras. Aparecen con un estilo diferente: negrita
- El apartado y el subapartado están numerados. Además de establecerse un orden, estos números nos permiten referenciar esos elementos. Así, en otras partes del documento podemos mencionar el apartado 1, el sub-apartado 1.1, etc...
Imaginemos ahora que este documento lo queremos escribir a través de otra persona, dictándoselo, o a través de una máquina con reconocimiento de voz, como Alexa. Si queremos obtener un resultado similar al anterior, no podemos meramente leer el texto tal cual. Es decir, NO funcionaría si decimos esto:
"Uno punto estructura mecánica está formada por las siguientes partes dos puntos chásis, cubierta y ruedas uno punto uno Chásis el chásis está diseñado para ser impreso en 3D punto consiste en una base hexagonal con dos vaciados rectangulares para el alojamiento de los motores..."
No funciona porque tenemos que añadir más información, no sólo el texto a escribir. Tenemos que explicar o indicar a qué categoría pertenece cada palabra (apartado, sub-apartado, párrafo), o qué atributos tiene esta palabra (negrita, cursiva) por ejemplo
Cuando usamos un lenguage para describir otro lenguaje o hablar sobre él, lo denominamos metalenguaje. Así, para obtener un documento como nosotros queremos tendríamos que decir algo como lo siguiente. Entre paréntesis se incluyen las palabras nuevas, que NO forman parte del texto que queremos escribir. Son las palabras del metalenguaje
"(Alexa comienza un documento nuevo) (Apartado 1) Estructura mecánica (Párrafo) Está formada por las siguientes partes: (Activa negrita)Chásis, cubierta y ruedas(Desactiva negrita) (Sub apartado 1.1) Chásis (Párrafo) El chásis está diseñado para ser (Activa negrita) impreso en 3D. Consiste en una (Activa negrita)base hexagonal(Desactiva negrita) con dos vaciados rectangualres..."
Las nuevas palabras que hemos añadido, NO tienen nada que ver con el documento técnico. No forman parte de este documento técnico. No se usan para describir nuestro robot ni aportar información técnica. Se usan para describir cómo representar las palabras del documento técnico: cada una, según su posición, con un estilo diferente
Así, las palabras y frases que hemos tenido que añadir para que una persona o una máquina (Alexa) nos escriba el documento técnico por nosotros son:
- Comienza un documento nuevo
- Apartado x
- Sub-apartado x
- Párrafo
- Activa negrita
- Desactiva negrita
Estas palabras forman nuestro Metalenguaje. Es nuestro LENGUAJE DE MARCADO, que nos permite hablar sobre el texto de nuestro interés. Con este ejemplo del dictado hemos visto que ESTAMOS OBLIGADOS a que existan estos metalenguajes, o de lo contrario no podríamos tener la posibilidad de desarrollar tecnología para que una máquina escriba o procese documentos por nosotros
Disponer de un documento descrito con un lenguaje de marcado nos permite crear una estructura de datos en árbol para representarlo. Esto permite que otros programas puedan recorrer este árbol para analizar todas sus partes y procesarlas
En una primera fase, un analizador síntáctico lee el documento y crea la estructura de árbol, siempre y cuando la sintáxis del documento sea correcta. En caso de no serlo el analizador reporta un error
En una segunda fase, este árbol se le pasa a otro programa para que lo recorra y procese la información. Ejemplos de procesado automático sería la generación de una tabla de contenidos, la traducción a otro lenguaje (como HTML, PDF...), su representación en un dispositivo, etc.
La sintaxis usada para dotar de estructura a los documentos depende del lenguaje de marcado empleado. En lenguajes como GML, SGML, XML, HTML, XHTML, etc se utilizan etiquetas para delimitar las zonas del documento. Típicamente las etiquetas (tags) se escriben usando una palabra situada entre los símbolos < y >. Hay una etiqueta para comenzar el nuevo bloque, y otra para terminarlo:
- Etiqueta de comienzo de bloque:
<nombre> - Etiqueta de final de bloque:
</nombre>
Para dar estructura a nuestro ejemplo, podríamos definir las siguientes etiquetas:
-
Documento:
<documento>y</documento> -
Apartado:
<apartado>y</apartado> -
Sub-apartado:
<subapartado>y</subapartado> -
Párrafo:
<parrafo>y</parrafo> -
Negrita:
<negrita>y</negrita>
Usando estas etiquetas, nuestro documento ejemplo lo escribiríamos así:
<documento>
<apartado>1. Estructura mecánica
<parrafo>
Está formada por las siguientes partes: <negrita>chásis</negrita>,
<negrita>cubierta</negrita> y <negrita>ruedas</negrita>
</parrafo>
<subapartado>1.1 Chásis
<parrafo>
El chásis está diseñado para ser <negrita>impreso en 3D</negrita>.
Consiste en una <negrita>base hexagonal</negrita> con dos vaciados rectangulares para el
<negrita>alojamiento de los motores</negrita>...
</parrafo>
</subapartado>
</apartado>
</documento>Muchas veces utilizamos los lenguajes de marcado (XML o HTML) para escribir documentación. Es decir, les damos una estructura para poder modificar su presentación: que aparezca letras resaltadas en negritas, que las letras de los títulos sean más grandes, etc... En estos casos los lenguajes de marcado se hacen pesados y oscuros. Y no aportan apenas ventajas
Por ello, han aparecido los lenguajes de marcas ligeros. Son los que usan por ejemplo en la Wikipedia, o en el texto que estás leyendo en esta wiki. El lenguaje que vamos a utilizar es markdown
En esta parte describimos el lenguaje Markdown y lo utilizaremos para crear nuestra primera wiki
El Markdown es un lenguaje de marcado ligero, utilizado en los ficheros Readme.md de github, y también para escribir documentos en su wiki (Es lo que haremos en esta asignatura). Su sintáxis es muy ligera y espartana, lo que hace que se aprenda MUY RÁPIDAMENTE. Es un lenguaje que se ha popularizado muchísimo para escribir las documentaciones e instrucciones de nuestros programas
Los encabezados se escriben con el caracter #. Se pueden tener hasta 6 niveles:
# Encabezado nivel 1
## Encabezado de nivel 2
### Encabezado de nivel 3
#### Encabezado de nivel 4
##### Encabezado de nivel 5
###### Encabezado de nivel 6Este es el resultado que producen en su presentación
El texto se escribe normalmente y se renderiza siempre en la misma línea. Para comenzar un párrafo nuevo hay que introducir dos saltos de línea. También se pueden tener texto en líneas separadas si al final de cada línea se introducen dos espacios y un salto de línea
# Prueba de texto
Este es un texto que está en
la misma línea, aunque en el
editor se escribe en líneas separadas
Esto comienza en un párrafo nuevo
porque se han puesto dos saltos de línea
Y esto está en líneas sepadas
porque tras cada linea hay
dos espacios y un salto de líneaAl renderizarlo vemos el efecto que tiene
Las listas sin numeración se crean con un asterisco * al comienzo de la línea. Se pueden anidar colocando dos espacios delante del asterisco
# Listas no ordenadas
* Elemento 1
* Otro elemento
* Más elementos
* Elemento anidado
* Anidado 2
* Anidado 3 Se renderizan así:
Podemos crear listas ordenadas escribiendo directamente los números seguidos de un punto
# Listas ordenadas
Estos son los puntos a seguir:
1. Leer la documentación
2. Practicar
3. Practicar más
4. Y seguir practicando más y másY este es el renderizado:
El texto se puede resaltar en cursiva colocando un * al comienzo y otro al final. Para resaltar en negrita se colocan dos asteriscos consecutivos **
# Resaltado de texto
Ejemplo de *texto en cursiva*
Ejemplo de **texto en negrita**Renderizado:
Cuando queremos insertar texto que represente código, utilizamos tres apóstrofos para indicar el comienzo (```) y otros tres para indicar el final
```
# -- Ejemplo de código en python
a = 2
print("Programa en python")
print(f"La variable a vale {a}")
```Esto se renderiza así:
Si tras el los tres apóstrofos iniciales indicamos el lenguaje de programación usado, se realizará un resaltado de sintáxis básico. Así, como el código anterior es python, lo podríamos poner así:
```python
# -- Ejemplo de código en python
a = 2
print("Programa en python")
print(f"La variable a vale {a}")
```y se renderizaría así:
También podemos insertar código dentro de la línea, poniéndolo entre apóstrofos (`)
En python la expresión `print(f" a + b = {2 + 1} ")` produce como resultado `a + b = 3` Se renderiza así:
Los enlaces a una página web externa se define utilizando esta notación: [Texto enlace](URL página). También podemos poner enlaces a cualquier encabezado definido en nuestro documento con esta sintáxis: [Texto enlace interno](#encabezado)
En este ejemplo se definen dos enlaces, uno externo y otro interno, al encabezado Enlaces
# Enlaces
## Enlaces externos
En wikipedia encontramos más información sobre [markdown](https://es.wikipedia.org/wiki/Markdown)
## Enlaces internos
Aquí hay información sobre [los enlaces](#Enlaces) en markdwonEsto es lo que se ve en el renderizado:
Las imágenes se introducen en el documento con la siguiente sintáxis:  donde imagen puede ser bien el nombre del fichero dentro de nuestro sistema de ficheros local o bien una URL de una imagen de internet
# Imágenes
## Imagen en fichero local
## Imagen en URL
Si tenemos el fichero Logo-urjc.png en la misma carpeta donde está guardado este fichero en markdown, el renderizado sería el siguiente:
Las citas se pone con el carácter > al comienzo:
# Citas
Un par de citas de Isaac Asimov:
> Escribo por la misma razón por la que respiro, porque si no lo hiciera, moriría
> Estoy convencido de que la autoeducación es el único tipo de educación que existeEste es el renderizado:
Se pueden hacer tablas muy básicas. El formato es el que utilizariamos si las quisieramos construir usando caracteres ASCII en un archivo de texto:
| | Col 1 | Col 2| Col 3| Col4 |
|---------|-------|------|------|------|
| Fila 1 | 1 | 2 | 3 | 4 |
| Fila 2 | 2 | 4 | 6 | 8 |
| Fila 3 | 3 | 6 | 9 | 12 |El renderizado queda así:
Esta es otra tabla que incluye texto y enlaces. Fijate que la cantidad de espacios usados no influye. Las celdas pueden estar descuadradas. Es el renderizador el que dibuja la tabla con el tamaño exacto:
| | node.js | Django | Flask | Electron |
|----------|-----------|--------|-------|----------|
| Lenguaje | Js | Python | Python| js |
| URL | [link](https://nodejs.org/es/) | [link](https://www.djangoproject.com/) | [Link](https://flask.palletsprojects.com/en/1.1.x/) | [Link](https://www.electronjs.org/) |
| Versión | 14.15.5 | 3.1.6 | 1.1.2 | 11.2.3 |Al renderizarlo queda así:
Es el momento de practicar. Primero practicaremos con el markdown, usando el VSCode. Después usaremos el markdown directamente en la wiki de nuestro repositorio personal
Todas las prácticas las haremos en nuestro repositorio personal, que debes crear en tu cuenta de github. Usa como nombre Mecatronica-2024-2025. Si no tienes el repositorio creado, aprovecha para crearlo ahora mismo
-
Crea el repositorio
Mecatronica-2024-2025
La creación de repositorios la vimos en la sesión de laboratorio L1. Pon un texto en la descripción y pincha en la casilla de verificación corespondiente para que se cree un fichero README.md inicial
- Clona el repositorio en tu orenador de trabajo
- Abre el proyecto desde el VSCode
-
Visualiza el fichero
README.md
Esto es lo que te debe aparecer:
Fíjate que el fichero README.md tiene la extensión .md. Esto significa que se trata de un fichero Markdown. Esto lo puedes ver también en la parte inferior derecha de la ventana del VSCode. Verás que dice Markdown
Los ficheros en Markdown están en texto plano por lo que se pueden editar con cualquir editor de textos. El VSCODE trae por defecto un visualizador de Markdowns, que nos permite ver una vista previa. Para ello pinchamos en el icono de la parte superior derecha (remarcado en rojo en la figura anterior). En la parte de la derecha nos aparecerá el texto renderizado
Vamos a practicar. Crearmos el fichero nuevo test.md. Como hemos usado la extensión .md el VSCode lo reconoce como Markdown y lo vemos escrito en la parte inferior
Ocultamos el explorador de archivos del VSCode (panel izquierdo) y abrimos la previsualización del fichero test.md
El previsualizador se actualiza según añadimos el código markdown, lo que resulta muy útil. Empezamos definiendo un encabezado y escribiendo un texto
Y ahora vamos añadiendo todos los elementos descritos en la sección anterior, para aprender y practicar (Se deja como ejercicio). No te olvides de subir la imagen del logo de la URJC (Logo-urjc.png), que debe estar junto al fichero test.md
El documento final será parecido a este:
A partir de un documento en markdown se pueden generar documentos en PDF y html. Desde VSCode hay muchas extensiones que nos permiten trabajar con markdown. Para realizar conversiones podemos usar por ejemplo la extensión Markdown PDF
Para instalarla nos vamos a parte de las extensiones en VSCode y escribirmos Markdown en el buscador. Seleccionamos Markdown PDF y le damos a install
Abrimos el documento test.md y pulsamos con el botón derecho del ratón. Se nos desplegará un menú que tiene las opciones para exportar a los diferentes formatos. Pinchamos en Export (PDF)
Al cabo de unos segundos se nos habrá generado el fichero test.pdf
En esta wiki es donde deberás escribir tu Bitácora personal mostrando todos tus avances, los retos realizados y las cosas que vas aprendiendo
Empezamos creando primero la wiki. Ve a la página principal de tu repositorio personal (Mecatronica-2024-2025). En mi caso se ve así:
Pinchamos en la pestaña que dice Wiki. Como todavía no tenemos ninguna wiki creada, nos aparecerá una pantalla como esta:
Pinchamos en el botón verde que dice Create the first page. Nos aparecerá una página como esta:
Ya podemos introducir los datos de la nueva página. El título que tiene por defecto es Home. Lo podemos cambiar al que más nos guste (página principal, documentación, etc...)
Por defecto la página está configurada para admitir markdown, que es el que usaremos, pero son válidos otros formatos. En la parte central es donde introducimos el texto. Por defecto se ha inicializado con el mensaje Welcome to the Mecatronica-2024-2025 wiki!
En la parte inferior podemos añadir (opcionalmente) comentarios a los cambios realizados. Pinchamos en el botón Save Page para crear y almacenar la página
Nos aparece el aspecto actual de la página. En la parte superior del navegador tenemos la URL completa de nuestra página principal de la wiki. Esta es la dirección que utilizaremos para dar acceso directo a otras personas a nuestra documentación
La dirección de la wiki de mi repositorio de ejemplo es: https://github.com/Obijuan/Mecatronica-2022-2023/wiki
En la parte superior derecha vemos que pone un "1" al lado de Pages. Esto nos indica que actualmente la wiki contiene sólo 1 página. Es la que acabamos de crear
Para modificar una página de la wiki pinchamos en el botón superior derecho que pone Edit. Vamos a editar nuestra página principal:
Al apretar el botón de EDIT entramos en el modo edición y podemos añadir más textos. Por defecto estamos en la pestaña que pone Write: modo de escritura
En cualquier momento podemos pinchar en la pestaña Preview para ver una previsualización del texto markdown actual. Como de momento sólo hemos introducido texto normal, no notaremos mucha diferencia (salvo que en el modo de previsualización NO nos permite escribir)
Volvemos a la pestaña Write para continuar escribiendo. Vamos a escribir un texto en Negrita. Para ello utilizamos los dos asterioscos colocados delante y detrás de la frase a convertir en negrita: **Texto en negrita**
Github nos ofrece la posiblidad de hacerlo a través de la interfaz web, seleccionando el texto y pinchando en el botón B. Nos añade automáticamente los dos asteriscos. En esta animación se muestra el proceso: Se añade el texto en negrita, se previualiza y se vuelve al modo write:
En la barra de formato (Marcada como 1 en la figura) tenemos más opciones: encabezados (h1, h2, h3), itálica, enlace, imágenes... Las netritas están marcadas con el número 2 en la figura:
Una vez terminada la edición, pinchamos en el botón de Save Page. Este es el aspecto actual de nuestra wiki:
Debajo del título (Home en mi caso) nos aparece el número de ediciones que hemos realizado hasta el momento: 2. Si pinchamos en ese enlace vemos el historial de la wiki: todos los cambios que se han realizado hasta llegar a la versión actual
En la izquierda están los comentarios de los cambios (por defecto, nos añade un nombre si nosotros no hemos escrito ningún comentario). En la derecha aparece un código que enlaza a la wiki que había en esa versión. Vamos a pinchar para ver cómo estaba:
En la URL que aparece en el navegador podemos ver si estamos accediendo a la última versión o bien a alguna anterior. Por ejemplo, la URL de la primera versión es:
https://github.com/Obijuan/Mecatronica-2022-2023/wiki/Home/b003e6eb5518355573f50624130c373f598b1b79
Mientras que la última versión de la página principal estará siempre en esta URL:
https://github.com/Obijuan/Mecatronica-2022-2023/wiki
Las imágenes en la wiki se añaden en dos pasos:
- Paso 1: Subir la imagen a tu repositorio
- Paso 2: Enlazar la imagen usando markdown desde la wiki
Como ejemplo de colocar una imagen en la wiki utilizaremos la que ya hemos subido previamente: El logo de la URJC ()
El paso 1 ya está, por tanto, completado: la imagen se encuentra ya en nuestro repositorio. Nos vamos al repositorio en la web y localizamos el fichero: copiamos su URL
Ahora editamos la wiki y ponemos el enlace a la imagen utilizando la notación markdown (también podemos usar la barra de formato)
Y así es como queda la wiki de momento
La única manera de dominar algo es practicando. Hay que practicar, practicar y practicar. Cuanto más se practique, mucho mejor
Puedes practicar como más te guste, pero yo te propongo aquí algunos retos
Una manera muy buena de comenzar una bitácora de trabajo (pública), es dando información sobre tí (¡Sin poner datos personales!). Una especie de mini-currículum: Formación, Intereses, situación actual, fotos...
Piensa en cómo organizar tu bitácora. Esta es la segunda sesión de Laboratorio, y ya hemos practicado con Github/VisualCode y el Markdown. Te propongo empieces la bitácora describiendo estas cosas que has aprendido, los problemas encontrados, cómo tienes pensado organizarla, etc...
- Créate el repositorio Mecatronica-2024-2025 en tu cuenta personal de github
- Créate una wiki en el repositorio Mecatrónica-2024-2025. Ahí estará tu bitácora personal
- Elige un responsable de tu grupo de trabajo
- El responsable debe crear el repositorio Mecatronica-Proyectos
- El responsable dede crear la wiki en el repositorio Mecatronica-Proyectos
- Haz los ejemplos de la sesión presencial
- ¡Haz los retos!
Tras finalizar esta sesión, ya tenemos todas las herramientas listas para documentar y almacenar nuestro proyecto y trabajo personal. Sabemos usar un repositorio desde VSCode, crear documentos en Markdown locales y escribir en las wikis de github
- Juan González-Gómez (Obijuan)
- Logo de Markdown: De Dustin Curtis - https://github.com/dcurtis/markdown-mark/tree/master/svg, CC0, https://commons.wikimedia.org/w/index.php?curid=31095459