Interno: Tutorial de Markdown (Lenguaje de edición de wiki) - AsambleaAutistaMadrid/General GitHub Wiki
⚠️ ¡AVISO!⚠️ Nos hemos mudado de web, ahora estamos en https://asambleautista.noblogs.org/
Markdown es un lenguaje ligero de marcado para editar documentos estructurados.
No requiere conocimientos de programación para aprenderlo. Es muy facil de exportar y de convertir a otros formatos puesto que es un estandar. Es super accesible puesto que no requiere de ninguna clase de programa propietario porque se usa edición de texto básica. El editor integrado de github de edición te permite usarlo sin aprenderte los "simbolos" de memoría.
Los tutoriales de Markdown están en inglés y eso no es accesible. Por otra parte, no eran suficientemente completos, concisos, etc.
Los problemas que tienen esos servicios son:
- Se depende de la existencia de una empresa
- Requieren de una cuenta exclusivamente de google, etc.
- No usan estandares y por lo tanto no son faciles de clonar, exportar y replicar en otro servidor/servicio.
- Para hacer edición sin internet presentan problemas o requiere instalar software privativo y restrictivo.
- La edición simultanea puede ser confusa y es muy facil de generar conflictos entre editores.
- No permiten referenciarse entre sí de la misma manera a la hora de editar. Los enlaces son mas complejos y no permite enlazar tan bien entre documentos, secciones del texto o incluso diferentes repositorios. Por otra parte, creo que probablemente ni siquiera necesites esa edición simultanea salvo para sesiones de lluvia de ideas.
A pesar de que es cierto que la edición en Markdown es menos visual que en los editores como a Microsoft Word, Libreoffice Documents, etc, tiene muchas ventajas:
- Utiliza lenguaje markdown estandar (texto) en vez de documentos en formatos binarios (docx, odt, pdf) esto facilita la edición y es mas accesible por lo cual no se depende de tener programas instalados extra. (Todo sistema operativo tiene un editor de texto básico).
- No requiere de una cuenta exclusiva para poder hostearlo.
- Tiene editor de texto integrado y accesble desde la web.
- La wiki es en si un repositorio git, lo cual implica:
- Facilidad clonar toda la wiki super rápido.
- Posibilidad de usar de SSH/HTTPS para subir cambios desde el dispositivo local o actualizar los cambios remotos.
- Posibilidad de hacer cambios granulares y posibilidad de retroceder a versiones anteriores en local de forma muy sencilla.
- Permite recrear la wiki en otro servicio de forma automatizada (tambien desde terminal).
- Que utiliza por debajo un estandar de gestión de proyectos muy eficiente.
- Que nadie va a necesitar guardar archivos binarios para editar texto. Lo cual es mucho mas reducido.
- Visitar una web cuyo contenido está escrito en markdown la hacer de por sí mucho mas ligera y simple. Es mucho mas rápida a la hora de visitarla y permite acceder al contenido a pesar de tener un dispositivo peor o peores conexiones para internet.
- Se puede seguir utilizando HTML, CSS (quien sepa) por debajo para editar elementos concretos que se salen de las limitaciones de Markdown.
Posibles inconvenientes:
- La gestión de archivos (imágenes) es algo compleja puesto que requiere de alojarlas y no es trivial.
- Hay que tener cuidado con realizar cambios "simultaneos" en un documento puesto que no permite edición en paralelo. Se podrían pisar los cambios de otra persona si alguien tiene una versión desactualizada.
- No es tan fácil recibir comentarios como en google docs o programas de edición de texto para revisión de escritos.
La especificación completa se puede encontrar en inglés aquí. El tutorial simplificado en inglés está aquí. Para cualquier duda, en la interfaz de edición de github hay un simbolo de "?" a la derecha de la barra superior en el que se pueden consultar estos elementos.
El estilo de markdown usado por github es un formato especial llamado Github Markdown o Github Flavored Markdown. A la hora de buscar recursos hay que tener en cuenta que podrían haber elementos no compatibles con otros tipos de markdown. Por eso recomiendo mirar este tutorial y la especificación oficial para dudas.
Voy a explicar los principales elementos visualmente.
Primero, para escribir es sencillo. Como en cualquier block de notas.
Pero la pregunta principal es: "¿Como se hacen los saltos de linea?".
Hay dos maneras:
La primera es dejar DOS espacios al final de una linea \
La segunda es usar una barra invertida al final de la linea separada por un espacio => X\
Para organizar el texto por niveles y secciones se usa lo siguiente:
# sección h1
## subsección h2
### subsubsección h3
###### sub sub sub sub sub sub sección h6
Listas no ordenadas => * ó - ó +
. Son equivalentes:
* Elemento 1
- Elemento 2
+ Elemento 3
- Elemento 1
- Elemento 2
- Elemento 3
Lista numerada => Numero seguido de un punto (1., 2., n.)
1. Elemento 1
2. Elemento 2
3. Elemento 3
- Elemento 1
- Elemento 2
- Elemento 3
Listas de compleción:
- [ ] Tarea 1
- [X] Tarea 2 completada
- Tarea 1
- Tarea 2 completada
Y se pueden combinar los tipos de listas y hacer sublistas. Tienen que ir separadas por cuatro espacios de indentación entre niveles.
- Elemento grande 1
1. Elemento pequeño 1
2. Elemento pequeño 2
- Elemento grande 2
- Elemento no numerado 1
* Elemento no numerado 2
- Elemento grande 3
1. [ ] Numero 1
1. [X] Numero 2
- Elemento grande 1
- Elemento pequeño 1
- Elemento pequeño 2
- Elemento grande 2
- Elemento no numerado 1
- Elemento no numerado 2
- Elemento no numerado 1
- Elemento grande 3
- Numero 1
- Numero 2
Para citar texto se usa => >
> Cita
>> Subcita 2
>>> Sub sub cita 3
Cita
Subcita 2
Sub sub cita 3
Para separar secciones manualmente se usa ***
o ---
Ejemplo:
- Para links normales se usa =>
[Texto del link](url)
- Para links de imágenes se añade un
!
al principio =>![Texto del link](url)
- Para direcciones de email se escriben como tal =>
[email protected]
[Texto del link de la página "Enlaces a recursos"](#enlaces-a-recursos)
[Texto del link local (Interno a la wiki) a la página principal](Home)
[Texto del link externo a la wiki a un video de youtube](https://www.youtube.com/watch?v=dQw4w9WgXcQ)
![Alt text o texto de la imagen\]\(Link de la imagen \)
[email protected]
Texto del link de la página "Enlaces a recursos"
Texto del link local (Interno a la wiki) a la página principal
Texto del link externo a la wiki a un video de youtube
[email protected]
- Negrita: Ejemplo 1 Ejemplo 2 =>
**Ejemplo 1**
o__Ejemplo 2__
- Cursiva: texto en cursiva =>
*Ejemplo 1*
o_Ejemplo 2_
- Tachado:
Ejemplo tachado=>~Ejemplo tachado~
- Subrayado Ejemplo subrayado =>
<u>Ejemplo subrayado</u>
o<ins>Ejemplo subrayado</ins>
- Monoespaciado:
Ejemplo 1
=> `Ejemplo 1` - Parrafo monoespaciado:
```
Ejemplo 1
```
Resultado:
Ejemplo 1 Ejemplo 2
-
Introducir nueva en lugares que no lo permita de la manera habitual
<br/>
=> Linea de arriba
Linea de abajo -
Emojis:
:+1: :pager: :100:
=> 👍 📟 💯
Si escribes:
en el editor de github, te salen sugerencias.
Visita la emoji cheatsheet