Markdown es un lenguaje de marcado ligero que se utiliza para formatear texto de manera sencilla, permite convertir texto a formato HTML para facilitar la creación de documentos, blogs y es ampliamente usado en muchas plataformas. Sobre todo para nuevos usuarios se pueden presentar una series de dificultades a la hora de aprender este lenguaje, sobre todo por la importancia que tiene cada carácter, incluyendo los espacios. Es importante familiarizarnos poco a poco con la sintaxis e incorporar cada carácter y recurso para trabajar de forma eficiente.
Hoy quiero hacer una pequeña recopilación de los errores más comunes para las personas que se inician a utilizar Markdown. Este artículo no pretende ser una guía de markdown. Partiendo de que ya te has enfrenado a este formato, analizaré errores comunes y algunas buenas prácticas.
1. Encabezados
Los encabezados nos ayudan a la organización de nuestros textos, permitiéndonos crear jerarquías y facilitando la navegación a los usuarios, es también una buena práctica SEO muy importante, ayudando a los motores de búsqueda a clasificar nuestro contenido. Los encabezados se crean usando el símbolo # seguido de un espacio y después pondremos el texto del encabezado. Añadiendo más símbolos # podremos disminuir el nivel del encabezado dentro del texto.
Si no dejas un espacio después del #, el texto no se renderizará como un encabezado (no se muestra en negritas y a mayor tamaño). En su lugar se creará una etiqueta.
Incorrecto
#Esto no es un Encabezado
Se ve así:
#Esto no es un Encabezado
Correcto
# Esto es un Encabezado
Se ve así:
Esto es un Encabezado
2. Enlaces
Para crear enlaces en Markdown se crean usando corchetes [] para el texto del enlace (el texto que verá el usuario de nuestro artículo) y paréntesis () para la URL. Si no cierras los paréntesis, el enlace no funcionará. Siempre debes cerrar correctamente los símbolos corchetes y paréntesis.
Incluir textos alternativos a nuestros enlaces es una muy buena práctica, dándole una imagen más profesional a nuestros artículos proporcionándole a nuestros lectores una mayor accesibilidad y una experiencia de usuario más cercana.
Incorrecto
[](www.google.com)
Se ve así:
Correcto
[Google](www.google.com)
Se ve así:
Google
3. Párrafos
Cuando creamos párrafos una muy buena practica es dejar una línea en blanco entre cada párrafo. De no dejar esta línea cada párrafo quedará unido al anterior. Estos bloques unidos son extremadamente difíciles para nuestros lectores y hace que nuestros textos se vean más largos e incómodos de leer.
Incorrecto
Este es el primer párrafo.
Este es el segundo párrafo.
Se ve así:
Este es el primer párrafo.
Este es el segundo párrafo.
Correcto
Este es el primer párrafo.
Este es el segundo párrafo.
Se ve así:
Este es el primer párrafo.
Este es el segundo párrafo.
4. Listas
Hay dos tipos principales de listas, ordenadas y desordenadas. Para crear listas sin un orden podemos usar un asterisco * , en cambio si queremos que nuestra lista muestre un orden usamos un número seguido de un punto 1. y un espacio antes del texto del elemento de la lista. Este espacio después del punto o el asterisco es muy importante, si no dejas un espacio, la lista no se mostrará correctamente.
Ejemplo
Lista desordenada:
* piña
* fresa
* mango
* uva
Lista ordenada:
1. Primero
2. Segundo
3. Tercero
4. Cuarto
Se ve así:
Lista desordenada:
- piña
- fresa
- mango
- uva
Lista ordenada:
- Primero
- Segundo
- Tercero
- Cuarto
5. Texto alternativo en las imágenes
A diferencia de los enlaces, las imágenes en Markdown se insertan usando un signo de exclamación ! seguido de corchetes [] para el texto alternativo y paréntesis () para la URL de la imagen. Si no cierras los paréntesis, la imagen no se mostrará.
Es muy importante colocar siempre que sea posible este texto alternativo. No solo mejorará el SEO de nuestro artículo (es usado para indexar nuestras páginas), si no que puede ser de mucha ayuda para personas invidentes. También permitirá que ante errores de cargas se muestre este texto, siendo más fácil la comprensión de nuestro artículo.
6. Bloques de Código
Cuando queremos mostrar fragmentos de códigos de una manera clara y diferenciada del resto de texto, es necesario usar tres backticks (`) , si en su lugar queremos mostrar un solo carácter simplemente lo encerramos entre uno.
Muy importante para mostrar el formato original de un texto correctamente sin que se interpreten los caracteres especiales. Además muchos editores interpretan distintos lenguajes de código resaltando las sintaxis y palabras claves para una mejor lectura y comprensión. Ejemplo de esto lo puedes ver a lo largo de este artículo donde lo he estado usando para la representación de los ejemplos.
7. Caracteres especiales
Como decía anteriormente conocer los caracteres especiales nos evitará más de un dolor de cabeza y problemas de formato. Toma su tiempo familiarizarse pero no es imposible. Caracteres como los asteriscos * tienen un importante papel, si quieres mostrarlo en tu texto tienes que ¨escapar¨ de ellos, esto se hace usando una barra invertida \
Incorrecto
* esto es un asterisco
Se ve así:
- esto es un asterisco
Correcto
\* esto es un asterisco
Se ve así:
* esto es un asterisco
8. Citas
Las citas destacan textos en nuestros artículo y tienen muchos usos., podemos usarlas para resaltar información ya sean citas textuales, referencias, comentarios e información contextual. Además los distintos visualizadores le suelen añadir un estilo diferente al texto, lo que puede ayudarnos a mejorar el estilo de nuestro artículo haciéndolo más atractivo y fácil de leer. Para crear citas en Markdown, usa el símbolo > al inicio de la línea. Muy importante dejar una línea en blanco al final de la cita para comenzar el siguiente párrafo.
Incorrecto
> Esta es una cita.
Esto NO es una cita
Se ve así:
Esta es una cita.
Esto NO es una cita
Correcto
> Esta es una cita.
Esto NO es una cita
Se ve así:
Esta es una cita.
Esto NO es una cita
Recomendaciones finales
Mi principal recomendación es que practiques diariamente, empieza creando documentos simples y añádele capas de complejidad utilizando distintos formatos. En línea podrás encontrar muchos recursos, guías y tutoriales que van desde los conceptos más básicos hasta los más avanzados. Utiliza editores de texto en pantalla dividida para poder ver como va tomando forma tus textos a medida que escribes, mis favoritos son el de GitHub y Obsidian, pero hay muchas opciones disponibles. También es muy útil en un principio crear tus propias plantillas o fragmentos de códigos con los distintos formatos. Espero que le sean útiles estos consejos y no se preocupen por cometer uno de estos errores, la práctica hace al maestro.
Quiero agradecerles sinceramente por tomarse el tiempo de leer este artículo. Su apoyo significa mucho para mí y me motiva a seguir compartiendo contenido que pueda ser útil e interesante para ustedes. Si encontraron este artículo útil o disfrutaron leyéndolo, les agradecería enormemente sus comentarios. Éxitos.
Common Markdown Mistakes and How to Avoid Them
Markdown is a lightweight markup language used to format text easily, allowing you to convert text to HTML format to facilitate the creation of documents, blogs, and it is widely used on many platforms. Especially for new users, a series of difficulties can arise when learning this language, mainly due to the importance of each character, including spaces. It is important to gradually familiarize yourself with the syntax and incorporate each character and resource to work efficiently.
Today I want to make a small compilation of the most common mistakes for people who are starting to use Markdown. This article is not intended to be a Markdown guide. Assuming you have already faced this format, I will analyze common mistakes and some best practices.
1. Headers
Headers help us organize our texts, allowing us to create hierarchies and facilitating navigation for users. It is also a very important SEO best practice, helping search engines classify our content. Headers are created using the # symbol followed by a space and then the header text. Adding more # symbols will decrease the header level within the text.
If you don’t leave a space after the #, the text will not render as a header (it won’t be bold and larger). Instead, it will create a tag.
Incorrect
#This is not a Header
It looks like this:
#This is not a Header
Correct
# This is a Header
It looks like this:
This is a Header
2. Links
To create links in Markdown, use brackets [] for the link text (the text that the user will see in our article) and parentheses () for the URL. If you don’t close the parentheses, the link won’t work. You should always correctly close the brackets and parentheses.
Including alternative texts for our links is a very good practice, giving a more professional image to our articles, providing our readers with greater accessibility and a closer user experience.
Incorrect
It looks like this:
Correct
Google
It looks like this: Google
3. Paragraphs
When creating paragraphs, a very good practice is to leave a blank line between each paragraph. If you don’t leave this line, each paragraph will be joined to the previous one. These joined blocks are extremely difficult for our readers and make our texts look longer and uncomfortable to read.
Incorrect
This is the first paragraph.
This is the second paragraph.
It looks like this:
This is the first paragraph. This is the second paragraph.
Correct
This is the first paragraph.
This is the second paragraph.
It looks like this:
This is the first paragraph.
This is the second paragraph.
4. Lists
There are two main types of lists: ordered and unordered. To create unordered lists, you can use an asterisk *. If you want your list to show an order, use a number followed by a period 1. and a space before the list item text. This space after the period or asterisk is very important; if you don’t leave a space, the list won’t display correctly.
Example
Unordered list:
* pineapple
* strawberry
* mango
* grape
Ordered list:
1. First
2. Second
3. Third
4. Fourth
It looks like this:
Unordered list:
- pineapple
- strawberry
- mango
- grape
Ordered list:
- First
- Second
- Third
- Fourth
5. Alternative Text for Images
Unlike links, images in Markdown are inserted using an exclamation mark ! followed by brackets [] for the alternative text and parentheses () for the image URL. If you don’t close the parentheses, the image won’t display.
It is very important to always include this alternative text whenever possible. It will not only improve the SEO of our article (it is used to index our pages), but it can also be very helpful for visually impaired people. It will also allow the alternative text to be displayed in case of loading errors, making it easier to understand our article.
!Image of a grape
6. Code Blocks
When we want to display code snippets clearly and distinctly from the rest of the text, it is necessary to use three backticks (`). If we want to display a single character instead, we simply enclose it between one backtick.
It is very important to display the original format of a text correctly without interpreting special characters. Additionally, many editors interpret different programming languages, highlighting syntax and keywords for better reading and understanding. You can see an example of this throughout this article where I have been using it to represent examples.
7. Special Characters
As I mentioned earlier, knowing special characters will save us more than one headache and formatting issues. It takes time to familiarize yourself, but it is not impossible. Characters like asterisks * play an important role. If you want to display it in your text, you have to “escape” it by using a backslash .
Incorrect
* this is an asterisk
It looks like this:
- this is an asterisk
Correct
\* this is an asterisk
It looks like this:
- this is an asterisk
8. Quotes
Quotes highlight texts in our article and have many uses. We can use them to emphasize information, whether they are textual quotes, references, comments, or contextual information. Additionally, different viewers usually add a different style to the text, which can help us improve the style of our article, making it more attractive and easier to read. To create quotes in Markdown, use the > symbol at the beginning of the line. It is very important to leave a blank line at the end of the quote to start the next paragraph.
Incorrect
> This is a quote.
This is NOT a quote
It looks like this:
This is a quote. This is NOT a quote
Correct
> This is a quote.
This is NOT a quote
It looks like this:
This is a quote.
This is NOT a quote
Final Recommendations
My main recommendation is to practice daily. Start by creating simple documents and add layers of complexity using different formats. Online, you can find many resources, guides, and tutorials that range from the most basic concepts to the most advanced. Use split-screen text editors to see how your texts take shape as you write. My favorites are GitHub and Obsidian, but there are many options available. It is also very useful at first to create your own templates or code snippets with different formats. I hope these tips are helpful, and don’t worry about making one of these mistakes; practice makes perfect.
I sincerely want to thank you for taking the time to read this article. Your support means a lot to me and motivates me to continue sharing content that can be useful and interesting for you. If you found this article useful or enjoyed reading it, I would greatly appreciate your comments. Best of luck.
 | I’m Ernesto, a Cuban passionate about art and writing. Always learning, always growing. Excited to share and learn more every day! I write about art, drawing, video games, nature, and review the things I like. My goal is to inspire and connect with others through my creative journey. |
|---|
Translated with DeepL.com (free version)
I apologize if there are any grammatical errors, English is not my native language, I have tried to be as careful as possible.
I regularly create images on Pixabay, which are free of copyright. Access my gallery by clicking here.
All assets, illustrations and banners have been created by me and are original content, unless otherwise specified.
The banner featured as the cover of this article was created using Canva.