Cómo escribir posts técnicos con ejemplos de código

5/8/2026

Un blog técnico funciona mejor cuando el código acompaña una decisión, no cuando aparece como relleno.

La idea es escribir el problema en lenguaje humano, enseñar el fragmento mínimo y cerrar explicando por qué esa solución merece estar ahí.

1. Definir una colección de contenido

En Astro puedes tipar tus posts para evitar publicar artículos incompletos. Este sería un esquema mínimo para un blog:

import { defineCollection } from 'astro:content'
import { glob } from 'astro/loaders'
import { z } from 'astro/zod'

const blog = defineCollection({
  loader: glob({ pattern: '**/*.mdx', base: './src/content/blog' }),
  schema: z.object({
    title: z.string(),
    author: z.string(),
    description: z.string(),
    pubDate: z.date(),
    tags: z.array(z.string()).default([]),
  }),
})

export const collections = { blog }

Esto hace que cada post tenga una estructura consistente: título, descripción, fecha y etiquetas.

2. Crear una ruta dinámica para cada post

La ruta lee todos los posts y genera una página estática por cada entrada:

---
import { getCollection, render } from 'astro:content'

export async function getStaticPaths() {
  const posts = await getCollection('blog')

  return posts.map((post) => ({
    params: { post: post.id },
    props: { post },
  }))
}

const { post } = Astro.props
const { Content } = await render(post)
---

<article>
  <h1>{post.data.title}</h1>
  <p>{post.data.description}</p>
  <Content />
</article>

La parte importante es render(post): convierte el contenido MDX en un componente que puedes insertar donde quieras.

3. Añadir un pequeño componente reutilizable

Si el post necesita una llamada visual, MDX permite importar componentes de Astro:

---
interface Props {
  label: string
}

const { label } = Astro.props
---

<aside class="note" aria-label={label}>
  <slot />
</aside>

Después podrías usarlo dentro de un .mdx para destacar una decisión o una advertencia.

4. Cuidar el estilo de los bloques de código

Un bloque de código debe poder leerse bien en móvil. Evita que rompa el layout:

pre {
  overflow-x: auto;
  border: 1px solid var(--border-color-subtle);
  border-radius: var(--radius-md);
  padding: var(--space-m);
}

code {
  font-size: 0.95em;
}

El scroll horizontal dentro del pre es preferible a romper toda la página.

5. Qué explicar después del código

Cada snippet debería responder a una pregunta:

Qué problema resuelve.
Qué parte es importante.
Qué tradeoff acepta.
Cómo se podría ampliar después.

Un blog técnico no demuestra nivel por enseñar mucho código. Lo demuestra por explicar qué merece quedarse y qué no.

Compartir artículo

Si te ha resultado útil, compártelo con alguien que esté construyendo su portfolio.