Consejos de formato Markdown para PDF profesionales

Un Markdown bien formateado produce PDF bien formateados. Esta guía cubre las técnicas que marcan la mayor diferencia en tu resultado final, desde la estructura de encabezados hasta el diseño de tablas y el estilo de bloques de código.

La jerarquía de encabezados importa

La estructura de tus encabezados determina el esquema del documento. Usa una jerarquía lógica:

# Título del documento (h1)
## Sección principal (h2)
### Subsección (h3)
#### Nivel de detalle (h4)

Consejos:

Un h1 por documento: se convierte en el título del PDF.
Usa h2 para las secciones principales (Introducción, Métodos, Resultados, Conclusión).
Usa h3 para subsecciones dentro de cada sección.
Evita saltar niveles (h2 → h4 sin h3).

La plantilla Legal numera automáticamente sus secciones de nivel superior, por lo que una jerarquía de encabezados clara mantiene esa numeración con sentido. En cualquier plantilla, una jerarquía lógica produce una estructura de documento más clara.

Tablas con aspecto excelente

Las tablas son una de las funciones más potentes. Así es como funcionan bien en los PDF:

| Proyecto | Estado | Presupuesto | Responsable |
| --- | --- | --- | --- |
| Rediseño web | En progreso | $45,000 | Ana |
| App móvil | Planificación | $30,000 | Carlos |
| Migración API | Completado | $15,000 | María |

Alineación de columnas

Usa dos puntos en la fila separadora para controlar la alineación:

| Artículo | Cant. | Precio |
| :--- | ---: | :---: |
| Alineado a la izquierda | Alineado a la derecha | Centrado |
| Widget | 5 | $240 |
| Servicio | 12 | $1,200 |

:--- — alineación a la izquierda (predeterminada)
---: — alineación a la derecha (buena para números)
:---: — alineación centrada

Escapar el carácter de tubería

Si el contenido de una celda contiene un |, escápalo con una barra invertida:

| Comando | Descripción |
| --- | --- |
| `cat file \| grep error` | Buscar errores en registros |

Consejos:

Mantén las etiquetas de columna cortas: los encabezados largos crean columnas anchas que pueden desbordarse.
Limítate a 4-5 columnas: más columnas dificultan la lectura en papel A4/Carta.
Previsualiza antes de exportar: las tablas anchas pueden necesitar etiquetas más cortas.

Bloques de código con resaltado de sintaxis

Envuelve el código entre tres comillas invertidas con una etiqueta de idioma. El PDF aplicará el resaltado de sintaxis automáticamente.

Sintaxis básica

```python
def calculate_growth(revenue: list[float]) -> float:
    if len(revenue) < 2:
        return 0.0
    return (revenue[-1] - revenue[-2]) / revenue[-2] * 100
```

Lenguajes comunes

Lenguaje	Etiqueta
Python	`python`
JavaScript	`javascript`
TypeScript	`typescript`
Bash / Shell	`bash`
SQL	`sql`
JSON	`json`
YAML	`yaml`
HTML	`html`
CSS	`css`
Rust	`rust`
Go	`go`
Java	`java`
C++	`cpp`

Ejemplo: Configuración JSON

```json
{
  "name": "quarterly-report",
  "templateId": "executive",
  "options": {
    "pageNumbers": true
  }
}
```

Ejemplo: Comandos de Shell

```bash
curl -X POST https://api.example.com/v1/reports \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"period": "Q3", "format": "pdf"}'
```

Consejos:

Incluye siempre la etiqueta de idioma — sin ella no hay resaltado.
Usa `código` entre comillas invertidas para referencias cortas como nombre_archivo o true.
Mantén los bloques por debajo de 50 líneas para una paginación limpia.

Imágenes en tus PDF

![Logotipo de la empresa](https://example.com/logo.png)

Requisitos:

Las imágenes deben ser URL accesibles públicamente (no archivos locales).
Formatos admitidos: PNG, JPEG, WebP.
Las imágenes se escalan automáticamente para ajustarse al ancho de la página.

Consejos:

Para logotipos en plantillas personalizadas, usa la función de carga de imágenes en lugar de imágenes Markdown.
Mantén las imágenes por debajo de 2 MB para un renderizado rápido.
Usa texto alternativo descriptivo: aparece si la imagen no se carga.

Citas para destacados

> **Hallazgo clave**: Los ingresos crecieron un 15 % interanual, superando nuestra proyección del tercer trimestre en 3 puntos porcentuales.

Las citas se renderizan con un borde izquierdo y sangría. Úsalas para:

Hallazgos o conclusiones clave
Citas o testimonios de clientes
Notas importantes o advertencias
Extractos de fuentes externas

Listas — con viñetas y numeradas

### Entregables clave

- Plan de marketing del cuarto trimestre
  - Calendario de redes sociales
  - Cronograma de campañas de correo
- Asignación presupuestaria
  - Desgloses departamentales
  - Reserva de contingencia

### Elementos de acción

1. Revisar el borrador con las partes interesadas
2. Incorporar comentarios antes del viernes
3. Presentar la versión final para aprobación
4. Archivar versiones anteriores

Consejos:

Usa listas con viñetas para elementos no ordenados.
Usa listas numeradas para pasos secuenciales.
Anida listas hasta 3 niveles de profundidad.
Deja una línea en blanco antes y después de las listas para un espaciado adecuado.

Enlaces y referencias

Consulta la [documentación de la API](https://markdowntopdfconverter.com/api-docs) para más detalles.

Para preguntas, contacta a [support@markdowntopdfconverter.com](mailto:support@markdowntopdfconverter.com).

Los enlaces se pueden hacer clic en el PDF. Usa texto de enlace descriptivo — evita “haz clic aquí.”

Diagramas Mermaid

Añade diagramas directamente en Markdown usando sintaxis Mermaid. Se renderizan como gráficos vectoriales nítidos en el PDF. La renderización de Mermaid requiere un plan premium.

Cada diagrama comienza con ```mermaid y una palabra clave de tipo en la siguiente línea.

Diagrama de flujo

Muestra procesos, decisiones y flujos de trabajo.

```mermaid
graph TD
    A[Start] --> B{Is approved?}
    B -->|Yes| C[Publish]
    B -->|No| D[Revise]
    D --> B
    C --> E[Done]
```

Puntos clave: graph TD = de arriba abajo. Usa LR para izquierda a derecha. [] = rectángulo, () = redondeado, {} = diamante, --> = flecha, -->|etiqueta| = flecha etiquetada.

Diagrama de secuencia

Muestra interacciones entre participantes a lo largo del tiempo.

```mermaid
sequenceDiagram
    Client->>Server: POST /api/convert
    Server->>Gotenberg: Render PDF
    Gotenberg-->>Server: PDF binary
    Server-->>Client: 200 OK (PDF)
```

Puntos clave: ->> = flecha sólida, -->> = respuesta discontinua. Los participantes se crean automáticamente a partir de los nombres.

Diagrama de Gantt

Planifica proyectos con barras de tiempo.

```mermaid
gantt
    title Q3 Launch
    dateFormat  YYYY-MM-DD
    section Design
    Wireframes    :2026-07-01, 7d
    Prototype     :2026-07-08, 5d
    section Build
    Frontend      :2026-07-13, 10d
    Backend       :2026-07-13, 12d
    section Launch
    QA            :2026-07-25, 4d
    Go Live       :milestone, 2026-07-30, 0d
```

Puntos clave: section agrupa tareas. Formato: NombreTarea :inicio, duración. milestone marca una fecha única.

Gráfico circular

Datos proporcionales simples.

```mermaid
pie title Revenue by Region
    "North America" : 45
    "Europe" : 30
    "APAC" : 25
```

Diagrama de clases

Muestra relaciones entre objetos para documentación técnica.

```mermaid
classDiagram
    User <|-- Admin
    User : +String email
    User : +login()
    Admin : +manageUsers()
    Report *-- User
    Report : +String title
    Report : +generatePdf()
```

Puntos clave: <|-- = herencia, *-- = composición. + = método/campo público.

Tipos adicionales

También compatibles: diagramas de estado, diagramas entidad-relación, mapas de viaje, gráficos git y gráficos de cuadrantes. Referencia completa de sintaxis en mermaid.js.org.

Consejos:

Mermaid se renderiza como SVG: se mantiene nítido en cualquier nivel de zoom.
Usa la plantilla Creative para documentos con muchos diagramas (pre-dimensiona los contenedores de diagramas).
Los diagramas se ajustan automáticamente al ancho de la página. Mantén las etiquetas de nodo concisas para evitar desbordamientos.
Prueba diagramas complejos en la vista previa en vivo antes de exportar.

Lista de verificación de estructura del documento

Antes de exportar, verifica:

Un título h1 en la parte superior
Jerarquía lógica de encabezados (h1 → h2 → h3)
Las tablas tienen un número coherente de columnas
Los bloques de código tienen etiquetas de idioma
Las imágenes tienen texto alternativo descriptivo
Los enlaces usan texto descriptivo
Las listas tienen líneas en blanco antes y después
Sin etiquetas HTML (usa Markdown puro)

Próximos pasos

Prueba estas técnicas en el convertidor con vista previa en vivo.
Aprende a diseñar una plantilla personalizada que use la tipografía de tu marca.
Compara las nueve plantillas integradas para encontrar la adecuada para tu contenido.