Para una nota Markdown que editas en Obsidian en un Mac y lees en GitHub, usa enlaces Markdown estándar y nombres de encabezado únicos en minúsculas. Las palabras sueltas, como setup, dan a ambos renderizadores el mismo destino; los encabezados con espacios requieren más atención.

Esta guía se centra en la navegación dentro de una nota y entre dos archivos Markdown. El objetivo práctico es mantener un documento legible sin dar por sentado que todos los renderizadores de Markdown interpretan los destinos de los encabezados de la misma manera.

¿Por qué un enlace Markdown válido puede no llevar a su encabezado?

Un enlace a un encabezado tiene dos requisitos distintos: el analizador de Markdown debe reconocer el enlace y el renderizador debe resolver su destino. Que el enlace sea clicable demuestra el primer requisito. Llegar a la sección prevista demuestra el segundo.

CommonMark define la sintaxis de encabezados y los enlaces que contienen fragmentos, incluido [link](#fragment). Sus ejemplos de encabezados no establecen un algoritmo universal para generar identificadores de encabezado. Esa diferencia explica por qué la sintaxis Markdown válida por sí sola no puede garantizar que la navegación entre secciones coincida en distintas aplicaciones. Consulta la especificación de encabezados de CommonMark y la especificación de enlaces.

GitHub genera anclas para los encabezados convirtiendo las letras a minúsculas, sustituyendo los espacios por guiones, eliminando los demás signos de puntuación y el formato, y diferenciando las anclas repetidas con sufijos numéricos. Obsidian documenta los enlaces a encabezados usando el texto del encabezado después de #. Son convenciones de destino distintas. Consulta las reglas de GitHub para enlaces a secciones y la documentación de Obsidian sobre enlaces internos.

Obsidian admite CommonMark y GitHub Flavored Markdown, además de sus propias extensiones. Esa compatibilidad no hace que todos los enlaces específicos de cada aplicación sean intercambiables: Obsidian advierte expresamente que algunas extensiones pueden aparecer como texto sin formato en otras aplicaciones. Su documentación de compatibilidad con Markdown describe este límite.

¿Qué convención de encabezados ofrece el mismo destino en ambos renderizadores?

Para una nota nueva que compartirás, elige nombres de encabezado únicos formados por letras ASCII minúsculas; cuando sea posible, usa una sola palabra. Para nombres más largos, una forma como desk-layout es una opción útil: el texto visible del encabezado ya coincide con el fragmento al estilo de GitHub.

Esta convención se deriva de las reglas documentadas; no es una función de compatibilidad independiente. Con setup, ninguno de los renderizadores tiene espacios, mayúsculas ni formato que interpretar de forma distinta. Es fácil comparar el encabezado visible con el destino.

Encabezado en el archivo Destino con el texto del encabezado de Obsidian, codificado para URL Destino generado por GitHub
## setup #setup #setup
## desk-layout #desk-layout #desk-layout
## Desk Layout #Desk%20Layout #desk-layout

La tabla aplica las indicaciones de Obsidian sobre el texto del encabezado y la codificación para URL y las reglas de GitHub para las anclas. Evita dar por sentado que Obsidian acepta todos los fragmentos normalizados por GitHub.

Hay una contrapartida visible: desk-layout se lee más como un identificador que como el título habitual de una sección. Si los títulos naturales son más importantes, consérvalos y verifica los enlaces en ambas aplicaciones. No cambies el nombre de todo un documento antes de decidir qué contrapartida conviene a sus lectores.

Una nota completa para probar

Crea una nota llamada desk-notes.md y pega en ella el siguiente Markdown. Es un documento de ejemplo completo con contenido ficticio; el bloque delimitado solo muestra el código fuente.

Desk notes

Jump to [setup](#setup), [materials](#materials), or
[desk layout](#desk-layout).

## setup

Place the notebook beside the keyboard.

## materials

Use a notebook, a pencil, and a desk tray.

## desk-layout

Keep the tray beside the notebook.

Return to [setup](#setup).

Observa que la etiqueta del enlace puede usar espacios normales: [desk layout](#desk-layout) muestra un texto legible y conserva el destino. No hace falta que todas las etiquetas de navegación parezcan identificadores de encabezado.

En una nota real, da suficiente contenido a las secciones para que la navegación sea visible. En un documento muy breve, es posible que el salto apenas se note porque toda la nota ya cabe en la ventana.

¿Cómo debes configurar y probar Obsidian en un Mac?

Empieza por la nota y luego ajusta cómo Obsidian genera los enlaces nuevos. Son comprobaciones distintas: cambiar una preferencia de generación de enlaces no sustituye la inspección del Markdown que ya existe.

  1. Abre Settings en la barra lateral.
  2. En Files and links, desactiva Use Wikilinks para que los enlaces generados usen la sintaxis Markdown.
  3. Configura New link format como Relative path to file para los enlaces entre archivos compartidos.
  4. Inspecciona los destinos existentes antes de confiar en la nueva configuración.

Obsidian documenta dónde encontrar los ajustes de escritorio y ambas preferencias para generar enlaces en Settings. Las rutas relativas son una opción útil aquí porque dejan explícita la estructura de carpetas compartida.

Cambia la nota de ejemplo a Reading view con Command+E y haz clic en cada enlace de navegación. Obsidian documenta ese atajo para macOS y explica que la vista de lectura oculta la sintaxis Markdown. Usa la misma vista para hacer comprobaciones repetibles, sin mezclar los gestos de edición con las pruebas de navegación. Consulta Vistas y modo de edición.

A continuación, inspecciona el archivo renderizado en GitHub. Pasa el cursor sobre un encabezado y haz clic en su icono de enlace para inspeccionar el fragmento real. Compáralo con el texto que aparece después de # en el enlace de origen. GitHub documenta este método de inspección en Enlaces a secciones.

Usa una pequeña lista de comprobación: el enlace aparece como tal, selecciona el archivo previsto y lleva al encabezado previsto. Anota los fallos según el destino en lugar de cambiar varios encabezados a la vez. Así será más fácil saber si una corrección resolvió un problema con el nombre del archivo, la ruta o el fragmento.

¿Cómo enlazas a un encabezado de otro archivo?

Empieza con un ejemplo sencillo: coloca dos archivos uno junto al otro. Crea index.md en la misma carpeta que desk-notes.md y añade este contenido completo:

Desk index

Read the [setup notes](desk-notes.md#setup).

Review the [desk layout](desk-notes.md#desk-layout).

El destino tiene dos partes: desk-notes.md selecciona el archivo y #setup selecciona la sección. GitHub resuelve los enlaces relativos a archivos desde el archivo actual; Obsidian ofrece un ajuste para generar rutas relativas. Estos comportamientos documentados permiten usar esta disposición en la misma carpeta. Consulta Enlaces relativos de GitHub y Ajustes de enlaces de Obsidian.

Conserva la misma disposición relativa al leer estos documentos. Si mueves solo index.md a una subcarpeta, el destino actual al archivo hermano dejará de corresponder a la disposición inicial. Recalcula la ruta antes de investigar el encabezado.

Mantén explícita la extensión .md en los enlaces a archivos compartidos. Si los nombres de archivo contienen espacios, usa %20 en los destinos Markdown, siguiendo las indicaciones de Obsidian sobre la codificación para URL. Codificar un espacio conserva el espacio; no convierte un encabezado en el ancla con guiones de GitHub.

¿Qué debes hacer con los encabezados existentes y los enlaces rotos?

Sigue esta secuencia de diagnóstico antes de añadir complementos u otros mecanismos de anclaje. Así aislarás el componente más pequeño que falla en el documento.

  1. Comprueba el encabezado en el código fuente. Confirma que el destino sea un encabezado Markdown real, como ## setup, con un espacio después de los signos de almohadilla iniciales. CommonMark exige esa separación en los encabezados que contienen texto. Consulta Encabezados ATX.
  2. Comprueba la sintaxis del enlace. Usa [setup](#setup). El corchete de cierre debe ir justo antes del paréntesis de apertura; [setup] (#setup) no es un enlace en línea según las reglas de enlaces de CommonMark.
  3. Separa la resolución del archivo de la resolución de la sección. Si falla un enlace entre archivos, prueba temporalmente un enlace al archivo sin el fragmento. Si falla, corrige primero la ruta.
  4. Compara el texto del encabezado con el fragmento. Para un título natural como Desk Layout, vuelve a comparar los renderizadores más arriba. Cambiar %20 por - cambia la convención de destino.
  5. Comprueba si hay destinos repetidos. Prefiere nombres distintos, como notebook-setup y tray-setup. Los sufijos numéricos de GitHub dependen del orden de las anclas duplicadas, por lo que cambiar el orden puede modificar los destinos. Consulta Enlaces a secciones de GitHub.

Si un documento ya tiene títulos de sección naturales, empieza por corregir su enlace de navegación más útil. Si hacer coincidir los fragmentos vuelve poco naturales los encabezados, mantén los destinos específicos de cada renderizador cuando sea necesario, en lugar de afirmar que una grafía no verificada es universal. Prueba exactamente el código fuente que piensas conservar.

Vuelve a comprobar los enlaces entrantes a una sección cada vez que cambies el nombre de un encabezado. El ajuste Automatically update internal links de Obsidian documenta la actualización de los enlaces cuando se cambia el nombre de un archivo; esa descripción por sí sola no basta para concluir que cualquier cambio en un encabezado reparará sus enlaces entrantes. Consulta la descripción del ajuste de Obsidian.

Para una nota compartida pequeña, el resultado más fácil de mantener suele incluir enlaces Markdown explícitos a archivos, destinos de encabezado únicos y una comprobación breve en cada renderizador tras los cambios estructurales. Empieza con la convención del ejemplo, conserva la disposición de los archivos y añade complejidad solo cuando un requisito concreto de navegación lo justifique.

Fuentes