Código inline, bloques y resaltado útil
Aprende a documentar comandos y fragmentos de código en Markdown usando `inline code`, bloques fenced y lenguaje declarado para que la guía sea más clara, más escaneable y menos ambigua.
Cuando una guía técnica menciona comandos, rutas o fragmentos de código, escribirlos como texto normal suele generar confusión. El lector ya no distingue qué debe copiar, qué es explicación y qué es solo contexto.
Markdown resuelve esto con dos herramientas distintas: el código inline para piezas cortas dentro de una frase y los bloques fenced para secuencias, comandos o ejemplos que merecen su propio espacio visual.
La habilidad importante aquí no es solo memorizar acentos graves, sino decidir qué formato ayuda mejor a ejecutar una acción sin errores. Una guía profesional reduce ambigüedad antes de que aparezca el fallo.
Esta lección te entrena para documentar comandos y snippets con claridad, declarando además el lenguaje cuando eso mejora la lectura y el resaltado.
- El inline code sirve para señalar un elemento puntual sin romper el flujo del párrafo.
- Si dentro de una explicación necesitas mencionar un comando, un nombre de archivo, una propiedad o una ruta breve, el código inline suele ser la mejor opción. Señala con claridad qué token debe leerse como literal.
- Esto evita errores típicos de lectura, como confundir una palabra explicativa con algo que el lector debe copiar. En documentación real, esa diferencia importa mucho.
- El error frecuente es abusar del inline code y meter frases completas o secuencias largas dentro de una línea. Ahí la lectura se vuelve densa y el formato deja de ayudar.
- Úsalo para comandos cortos como `npm run dev`.
Cuándo usar código inline
El inline code sirve para señalar un elemento puntual sin romper el flujo del párrafo.
Si dentro de una explicación necesitas mencionar un comando, un nombre de archivo, una propiedad o una ruta breve, el código inline suele ser la mejor opción. Señala con claridad qué token debe leerse como literal.
Esto evita errores típicos de lectura, como confundir una palabra explicativa con algo que el lector debe copiar. En documentación real, esa diferencia importa mucho.
El error frecuente es abusar del inline code y meter frases completas o secuencias largas dentro de una línea. Ahí la lectura se vuelve densa y el formato deja de ayudar.
- Úsalo para comandos cortos como `npm run dev`.
- Úsalo para archivos como `README.md` o `.env`.
- Úsalo para props, flags o rutas breves.
- Si el contenido ocupa varias líneas o varios pasos, ya pide bloque.
Bloques fenced y lenguaje declarado
Un bloque de código crea espacio visual y reduce el riesgo de copiar mal un snippet.
Cuando el lector necesita copiar varias líneas, revisar una configuración o comparar una salida esperada, conviene sacar el contenido a un bloque fenced con tres acentos graves.
Además, declarar el lenguaje después de la apertura mejora el resaltado y la legibilidad en muchos renderizadores. No cambia el contenido, pero sí ayuda a leer mejor.
Esto es especialmente útil en documentación mixta: `bash` para terminal, `json` para configuración, `js` para un ejemplo corto o `md` para enseñar Markdown dentro de Markdown.
Cómo documentar comandos sin ambigüedad
Una buena guía separa claramente explicación, acción y resultado esperado.
Un patrón muy útil es explicar primero qué se va a hacer, mostrar después el comando o snippet en bloque y, si hace falta, cerrar con una nota breve sobre qué debería ocurrir.
Eso evita que la persona nueva intente copiar un párrafo entero o no sepa qué parte exacta debe ejecutar. En Markdown, claridad visual y claridad operativa suelen ir juntas.
