Skip to main content

Markdown

Markdown es una forma de formato de texto que se utiliza comúnmente para escribir en plataformas en línea. Permite agregar formato básico, como negrita, cursiva, encabezados y listas, utilizando una sintaxis simple y legible. Con Markdown, puedes estructurar tu texto de manera clara y hacerlo más atractivo visualmente sin necesidad de conocer complicadas etiquetas de HTML u otros lenguajes de marcado. Es ampliamente utilizado en plataformas de blogs, foros, sitios web de documentación y aplicaciones de toma de notas para facilitar la escritura y la lectura.

Sintaxis​

  1. Encabezados:

    • Para crear un encabezado, utiliza el símbolo "#" seguido de un espacio y el texto del encabezado. Puedes utilizar hasta seis "#" para encabezados de diferentes niveles, donde un "#" representa el encabezado de nivel 1 y "######" el de nivel 6.

    Ejemplo:

    # Encabezado de nivel 1
    ## Encabezado de nivel 2
    ### Encabezado de nivel 3

  2. Negrita y cursiva:

    • Para escribir en negrita, envuelve el texto entre dos asteriscos (**) o dos guiones bajos (__).
    • Para escribir en cursiva, envuelve el texto entre un asterisco (*) o un guión bajo (_).

    Ejemplo:

    **Texto en negrita**
    __Texto en negrita__
    *Texto en cursiva*
    _Texto en cursiva_

  3. Listas:

    • Puedes crear listas ordenadas o desordenadas.
    • Para una lista desordenada, utiliza "*", "+", o "-" seguido de un espacio.
    • Para una lista ordenada, utiliza números seguidos de un punto y un espacio.

    Ejemplo:

    - Elemento 1
    - Elemento 2
      - Subelemento A
      - Subelemento B
    1. Primer elemento
    2. Segundo elemento

  4. Enlaces e imágenes:

    • Para crear un enlace, envuelve el texto que quieres que sea el enlace entre corchetes [], seguido de la URL entre paréntesis ().
    • Para agregar una imagen, utiliza la misma sintaxis que para los enlaces, pero precede el texto con un signo de exclamación (!).

    Ejemplo:

    [Texto del enlace](http://www.ejemplo.com)
    ![Texto alternativo](ruta/a/la/imagen.jpg)

  5. Bloques de código:

    • Para resaltar bloques de código, puedes utilizar comillas simples (`) para una línea de código o tres comillas (```) para bloques de código multilínea.

    Ejemplo:

    `Código en una sola línea`

    Código en varias líneas

  6. Citas:

    • Para citar texto, utiliza el símbolo ">" seguido del texto de la cita.

    Ejemplo:

    > Esto es una cita.

  7. Líneas horizontales:

    • Para insertar una línea horizontal, utiliza tres asteriscos (***) o guiones (---) en una línea separada.

    Ejemplo:

    ***

  8. Tablas:

    • Para crear tablas, utiliza barras verticales (|) para separar las columnas y guiones (-) para separar la fila del encabezado del resto de las filas. Puedes alinear el texto dentro de las celdas utilizando dos puntos (:).

    Ejemplo:

    | Encabezado 1 | Encabezado 2 | Encabezado 3 |
    |--------------|:------------:|-------------:|
    | Celda 1      | Centro       | Derecha      |
    | Celda 2      | Alineado     | Alineado     |

  9. Bloques de texto:

    • Para resaltar bloques de texto, puedes utilizar un solo asterisco (*) o guión bajo (_) para resaltar, o tres de ellos (*** o ___) para crear una sección separada.

    Ejemplo:

    *Texto resaltado*
    _Otro texto resaltado_

    ***

    Texto en una sección separada.

  10. Escape de caracteres:

    • Si necesitas utilizar un caracter especial que normalmente tendría un significado en Markdown, puedes "escaparlo" precediéndolo con una barra invertida (). Esto evitará que Markdown lo interprete.

    Ejemplo:

    \* Esto no se interpretará como negrita \*

  11. Comentarios:

    • Aunque no es parte de la especificación oficial de Markdown, algunas implementaciones permiten agregar comentarios en el texto. Estos comentarios no se renderizarán en el resultado final.

    Ejemplo:

    <!-- Este es un comentario -->

  12. Referencias de estilo de texto:

    • Algunas implementaciones de Markdown permiten definir estilos de texto que pueden ser reutilizados. Por ejemplo, puedes definir un estilo llamado "énfasis" que se renderizará como texto en cursiva.

    Ejemplo:

    [^1]

    [^1]: *Texto en cursiva*

Documentación del código fuente​

El PEP 8, la guía de estilo para código Python, proporciona directrices sobre cómo comentar el código de manera efectiva. Aquí hay algunas recomendaciones sobre cómo hacer comentarios internos en el código fuente:

  1. Claridad y Concisión: Los comentarios deben ser claros y concisos, explicando el propósito o la funcionalidad del código sin ser demasiado verbosos.

  2. Evita comentarios obvios: No comentes el código obvio. Por ejemplo, no necesitas comentarios que digan "suma uno a la variable 'x'".

  3. Explicar el por qué, no el qué: En lugar de explicar qué hace una línea de código específica, es más útil explicar por qué se está haciendo algo de una manera particular. Esto ayuda a los desarrolladores a comprender la lógica detrás del código.

  4. Comentarios en líneas de código: Si es necesario, los comentarios en línea pueden ser útiles para aclarar partes específicas del código. Sin embargo, no los uses en exceso, ya que pueden dificultar la legibilidad del código.

  5. Docstrings: Para funciones, clases y módulos, utiliza docstrings para proporcionar una descripción más detallada de su propósito, entrada, salida y cualquier otra información relevante. Las docstrings son cadenas de texto que aparecen al principio de estas estructuras y se encierran entre triple comillas (""").

Por ejemplo:

def calcular_area(base, altura):
    """
    Calcula el área de un triángulo.

    :param base: La longitud de la base del triángulo.
    :param altura: La altura del triángulo.
    :return: El área del triángulo.
    """
    return 0.5 * base * altura

  1. Mantenimiento de comentarios: Asegúrate de mantener los comentarios actualizados a medida que el código evoluciona. Los comentarios obsoletos pueden ser más perjudiciales que útiles.

  2. Comentarios en bloques de código: A veces es útil colocar comentarios antes de bloques de código para explicar su propósito general.

En Markdown​

¡Claro! Utilizar Markdown para los comentarios en el código puede hacer que sean más legibles y estructurados. Aquí hay un ejemplo de cómo podrías aplicar Markdown a los comentarios en Python:

def calcular_area(base, altura):
    """
    # Calcula el área de un triángulo.

    **Args:**
        base *(float)*: La longitud de la base del triángulo.
        altura *(float)*: La altura del triángulo.

    **Returns:**
        float: El área del triángulo.
    """
    return 0.5 * base * altura

Otros formatos​

# Google Docstrings
"""
    This is an example of Google style.

    Args:
        param1: This is the first param.
        param2: This is a second param.

    Returns:
        This is a description of what is returned.

    Raises:
        KeyError: Raises an exception.
"""

# reST
"""
    This is a reST style.

    :param param1: this is a first param
    :param param2: this is a second param
    :returns: this is a description of what is returned
    :raises keyError: raises an exception
"""

#  Epytext

"""

    @param param1: this is a first param
    @param param2: this is a second param
    @return: this is a description of what is returned
    @raise keyError: raises an exception
"""