# Escribe en Markdown

Redacta con el Markdown de siempre y obtén un PDF o un documento editable para tus colaboradores.

Markdown funciona bien para notas de investigación, informes y primeros borradores. Oleafly le da una barra de formato propia y una ruta de compilación con Pandoc, con archivos de código que puedes usar fuera de la app.

## Crea un informe

1. Elige **Proyecto nuevo → Usar una plantilla → Blank Markdown document**.
2. Ponle al proyecto el nombre **Notas de campo** y abre `main.md`.
3. Pega este ejemplo y elige **Recompilar** o pulsa **⌘Enter / Ctrl+Enter**.
4. Si Oleafly se ofrece a configurar un motor necesario, completa esa configuración y vuelve a compilar.

```markdown title="main.md"
---
title: "Field notes"
author: "Alex Chen"
date: ""
---

# Question

Does the revised procedure reduce measurement time?

## Method

1. Prepare the sample.
2. Repeat the measurement three times.
3. Record the elapsed time.

## Observations

| Run | Time (s) | Note |
| --- | --- | --- |
| 1 | 12 | First pass |
| 2 | 10 | Repeated pass |

The **mean time** will be compared with the baseline.
```

El PDF debería incluir un título, encabezados, una lista numerada y una tabla. Los metadatos entre el primer par de líneas `---` controlan el título y el autor del documento.

## Tipos de documento

Añade una línea `type` al front matter para compilar el documento como informe, libro, diapositivas, póster, carta o currículum. Sin `type`, o con un valor que Oleafly no conoce, el documento se compila como artículo.

| `type` | Qué genera | Se rellena salvo que lo definas tú |
| --- | --- | --- |
| `article` | Un artículo | Nada |
| `report` o `thesis` | Un informe, con un capítulo en cada encabezado `#` | `documentclass: report` |
| `book` | Un libro, con un capítulo en cada encabezado `#` | `documentclass: book` |
| `slides` | Diapositivas Beamer 16:9. Un encabezado `#` inicia una sección y un encabezado `##` inicia una diapositiva | `aspectratio: 169` |
| `poster` | Un póster Beamer de una página, encabezado por su `title`, `subtitle`, `author` e `institute` | Papel A0, vertical |
| `letter` | Una carta con tu dirección y la del destinatario, un asunto, un saludo y una despedida | `documentclass: scrlttr2` |
| `cv` | Un artículo compacto | `geometry: margin=2cm` y `pagestyle: empty` |

Tu propio front matter manda. Un valor que definas tú, como `documentclass`, `aspectratio` o `geometry`, sustituye al que rellena el tipo.

Para las diapositivas, define `slide-level` para elegir el nivel de encabezado que inicia una diapositiva. Con `slide-level: 1`, cada encabezado `#` inicia una. Las diapositivas se compilan como un PDF normal, así que **Presentar** en la barra de herramientas de la vista previa puede mostrarlas. Consulta [Presentar diapositivas](/docs/present-slides/).

Un póster es A0 salvo que definas `papersize` como `a1`, `a2`, `a3` o `a4`. Se ignoran otros tamaños, como `letter` o `a5`. Añade `orientation: landscape` para un póster apaisado.

Una carta toma la dirección del destinatario de `to` y la tuya de `from`. `opening` es el saludo y `closing` es la línea anterior a tu nombre, que sale de `author`. `subject` se convierte en la línea de asunto, o `title` si no hay `subject`. Escribe una dirección como una lista, con una línea por elemento.

```markdown title="main.md"
---
type: letter
author: "Alex Chen"
from:
  - "Department of Physics"
  - "1 University Road"
to:
  - "Dr. Sam Lee"
  - "Editorial Office"
subject: "Revised manuscript"
opening: "Dear Dr. Lee,"
closing: "Yours sincerely,"
---

Thank you for the reviewers' comments. The revised manuscript answers each one.
```

**Tipo de documento** en [Ajustes del documento](/docs/document-settings/#markdown) escribe la línea `type` por ti. Una [exportación a LaTeX](/docs/export/#what-each-format-keeps) también sigue el tipo, y una [exportación a PowerPoint](/docs/export/#presentation-and-book-exports) de diapositivas usa el mismo `slide-level`. [`oleafly build`](/docs/cli/#build-a-project) compila todos los tipos como lo hace la app.

## Edición de código y edición visual

El interruptor del principio de la barra tiene tres modos. **Código** edita el Markdown directamente. **Visual** ofrece edición con formato para títulos, párrafos, listas, enlaces, imágenes y tablas. **Ambos** muestra a la vez el código y el texto con formato. Abre su menú para elegir **Apilado** o **Dividir**. Los proyectos nuevos se abren en Código y cada proyecto recuerda el modo en que lo dejaste.

Subrayado, resaltado, superíndice y subíndice son controles de formato de Pandoc en el modo Código. Sus botones se ocultan en el modo Visual. Usa Código cuando trabajes con metadatos, con la sintaxis de las citas o con otras construcciones del código.

[Descarga el código del ejemplo](/examples/writing-example.md)

## Todas las herramientas de la barra

Selecciona texto antes de hacer clic en un control de formato. En el modo Código, la mayoría de las herramientas envuelven la selección o insertan un marcador de posición. Abre **Más opciones de formato** (`…`) para llegar a los controles que no caben en la barra.

### Código / Visual

Cambia entre **Código**, **Visual** y **Ambos**. El documento sigue siendo código de Markdown en todos los modos.

### Deshacer

Revierte la última edición. ⌘Z / Ctrl+Z.

### Rehacer

Restaura una edición deshecha. **⌘Shift+Z / Ctrl+Shift+Z**.

### Título → Título

Elige **Título** en el menú de títulos para insertar `# Title`. Sustituye el texto del título por el tuyo.

### Título → Sección

Elige **Sección** en el menú de títulos para insertar `## Section`. Sustituye el texto del título por el tuyo.

### Título → Subsección

Elige **Subsección** en el menú de títulos para insertar `### Subsection`. Sustituye el texto del título por el tuyo.

### Título → Subsubsección

Elige **Subsubsección** en el menú de títulos para insertar `#### Subsubsection`. Sustituye el texto del título por el tuyo.

### Título → Título menor

Elige **Título menor** en el menú de títulos para insertar `##### Minor heading`. Sustituye el texto del título por el tuyo.

### Título → Título de párrafo

Elige **Título de párrafo** en el menú de títulos para insertar `###### Paragraph heading`. Sustituye el texto del título por el tuyo.

### Lista con viñetas

Empieza una lista sin orden. `- Item`.

### Lista numerada

Empieza una secuencia. `1. Item`.

### Lista de tareas

En el modo Código, añade una tarea y cambia `[ ]` por `[x]` cuando esté completa. `- [ ] Task`.

### Cita en bloque

Coloca una cita en su propia línea. `> quoted text`.

### Negrita

Da énfasis al texto seleccionado. `**text**`; ⌘B / Ctrl+B.

### Cursiva

Da énfasis a un término. `*text*`; ⌘I / Ctrl+I.

### Tachado

Marca un texto como sustituido. `~~text~~`.

### Código en línea

Da formato a un nombre de archivo, un comando o un identificador. Texto entre acentos graves.

### Subrayado

Selecciona una frase en el modo Código. `[text]{.underline}`.

### Resaltado

Selecciona una frase en el modo Código. `[text]{.mark}`.

### Superíndice

Selecciona el exponente en el modo Código. `^text^`.

### Subíndice

Selecciona el subíndice en el modo Código. `~text~`.

Subrayado y resaltado usan atributos de Pandoc para que el formato pueda llegar al PDF. Usa estos controles en lugar de añadir etiquetas HTML sin procesar al manuscrito.

### Insertar un enlace

En el modo **Código**: inserta `[link text](url)`. Sustituye los dos marcadores de posición.

En el modo **Visual**: abre **URL del enlace**. Escribe la dirección y aplícala a tu selección. Usa **Quitar el enlace** para conservar el texto sin el enlace.

### Insertar una imagen

En el modo **Código**: inserta `![caption](image-filename)`. Sustituye la ruta y el pie.

En el modo **Visual**: abre **Archivo de imagen**. Escribe una ruta del proyecto, como `figures/plot.png`, y aplícala.

Las imágenes PNG, JPG, PDF, SVG, GIF, WebP y BMP entran todas en el PDF. Oleafly convierte SVG, GIF y WebP por ti al compilar. Las imágenes TIFF, AVIF, HEIC y JPEG XL no pueden entrar: la compilación se detiene y nombra el archivo, así que guárdalo en uno de los otros formatos y compila otra vez. Si falla una conversión, comprueba que la imagen se abre, o guárdala como PNG o PDF.

### Insertar una tabla

En el modo **Código**: inserta tres columnas, un encabezado y dos filas de datos. Sustituye los nombres de las columnas y las celdas.

En el modo **Visual**: inserta una tabla editable con las mismas dimensiones iniciales.

### Dibujar un diagrama

Abre el [compositor de diagramas](/docs/figures-diagrams/) en modo Mermaid. Dibuja un diagrama de flujo en el lienzo o edita el código de Mermaid y luego elige **Insertar como Mermaid** para añadirlo en el cursor como un bloque de código `mermaid` delimitado. Consulta [Diagramas de Mermaid](#mermaid-diagrams).

### Análisis del documento

Enumera los títulos, las figuras, las tablas, las ecuaciones, las etiquetas, las citas y las tareas pendientes del documento en el orden del código, cada uno enlazado con su línea. También lee el título, los autores, las palabras clave, la fecha y el resumen del front matter y puede copiarlos para un formulario de envío. Consulta [Análisis del documento](/docs/document-insights/).

### Ajustes del documento

Cambia el tipo de documento, la clase del documento, el tamaño de página, las columnas, los márgenes, la tipografía del texto, el tamaño de letra, el idioma, el interlineado y la numeración de las secciones. Oleafly escribe tus elecciones en el front matter en YAML que lee Pandoc y añade un bloque de front matter si el archivo no tiene ninguno. Consulta [Ajustes del documento](/docs/document-settings/#markdown).

### Información del proyecto

En el modo **Código**: muestra las estadísticas del proyecto y la información de la selección.

En el modo **Visual**: muestra las estadísticas de la superficie de edición visual.

### Buscar

En el modo **Código**: abre la búsqueda del archivo activo con ⌘F / Ctrl+F.

En el modo **Visual**: el botón Buscar de la barra de código está oculto.

Importa la imagen a través del árbol de archivos antes de referenciarla. Mantén las rutas de las imágenes relativas al manuscrito, para que el archivo comprimido del código funcione en otro ordenador.

![Un cuaderno de laboratorio en Markdown editado en las vistas de código y visual, con la tabla y la lista de tareas siempre sincronizadas.](https://cdn.oleafly.com/images/gifs/desktop/markdown-notebook.gif?v=2)

## Ecuaciones y bloques de código

Escribe las fórmulas en línea como `$x^2$`. Pon una ecuación en bloque entre dos pares de signos de dólar:

```markdown
$$
\bar{x} = \frac{1}{n}\sum_{i=1}^{n}x_i
$$
```

Para un ejemplo de código, encierra el código entre tres acentos graves y pon su lenguaje después de la valla de apertura. Son construcciones del código; la barra de Markdown no tiene un botón aparte para las ecuaciones ni para los bloques de código delimitados.

En el modo Visual, un bloque delimitado sigue siendo un bloque de código y conserva su lenguaje y sus líneas en blanco, de modo que los diagramas de Mermaid sobreviven. Escribe tres acentos graves para empezar un bloque nuevo y pulsa Tab para sangrar dentro de uno.

## Diagramas de Mermaid

Elige **Dibujar un diagrama** en la barra para crear un diagrama de flujo de Mermaid en el compositor de diagramas. **Insertar como Mermaid** lo añade como un bloque de código delimitado:

````markdown
```mermaid
flowchart LR
  A[Sample] --> B[Measure]
```
````

En el modo **Ambos**, el lado con formato dibuja el bloque como un diagrama. Un PDF necesita una imagen, así que el compositor también guarda un PNG generado en `figures/mermaid-<hash>.png`, y la compilación coloca esa imagen en lugar del bloque. Por eso el diagrama también aparece en el PDF compilado, y en las exportaciones a Word, HTML, EPUB y PowerPoint. Si después editas el bloque a mano, el PDF muestra el código hasta que vuelvas a insertar o guardar el diagrama desde el compositor. Consulta [Mermaid en documentos de Markdown](/docs/figures-diagrams/#mermaid-in-markdown-documents).

## Texto en otros idiomas

Oleafly elige tipografías para las escrituras que encuentra en el documento, así que el coreano, el japonés, el chino, el árabe, el hebreo, el griego, el cirílico, el devanagari, el tailandés y varias escrituras más se ven sin ninguna configuración. Los símbolos y los emoji también reciben una tipografía, con los emoji en blanco y negro. Un documento escrito sobre todo en árabe o hebreo se lee de derecha a izquierda.

Los caracteres chinos aparecen tanto en textos chinos como japoneses, así que define `lang` en el front matter para obtener la tipografía correcta: `ja` para japonés, `zh` para chino simplificado, `zh-TW` para chino tradicional o `ko` para coreano. Sin `lang`, Oleafly se guía por el texto: el kana indica japonés y el hangul indica coreano.

```markdown title="main.md"
---
title: "実験ノート"
lang: ja
---
```

Las tipografías que eliges tú tienen prioridad. Cuando el front matter define `mainfont` o `CJKmainfont`, o `header-includes` configura tipografías, Oleafly deja esa parte en paz.

### Caracteres que faltan en el PDF

Cuando ninguna tipografía en uso tiene un carácter, el PDF se genera igualmente sin él, y la compilación muestra una advertencia con una muestra de los caracteres que faltan. Para arreglarlo:

- Para texto en coreano, chino o japonés, define `CJKmainfont` en el front matter con una tipografía instalada en tu ordenador que tenga los caracteres.
- Para otro texto, define `mainfont` del mismo modo. **Tipografía del texto**, en [Ajustes del documento](/docs/document-settings/#markdown), lo escribe por ti.
- Para un símbolo poco común, usa una imagen.

## Citas y bibliografía

Importa o crea `references.bib`, añade `bibliography: references.bib` a los metadatos YAML y cita una clave existente con `[@citation-key]`. Pandoc usa la bibliografía para generar las citas con formato y una lista de referencias.

Si el front matter no nombra ninguna bibliografía, o nombra un archivo que no existe, la compilación usa los archivos `.bib` del proyecto que contienen las claves que citas. Una cita sin ninguna bibliografía se queda en el PDF tal como la escribiste, como `[@smith2020]`, para que puedas escribir primero y añadir las referencias después. Un documento que no cita nada se compila sin leer ningún archivo `.bib`.

[Busca y gestiona referencias →](/docs/citations/)

## Importar y exportar

Para mantener en Markdown un borrador existente, crea un Blank Markdown document, pega el borrador en `main.md` e importa sus imágenes y su bibliografía. La importación independiente **Documento de Markdown** de la biblioteca convierte por ahora un borrador a LaTeX. [Rutas de importación](/docs/import-project/) explica las dos vías.

Compila para obtener un PDF, o usa **Exportar** para crear Word, HTML, Typst, LaTeX, PowerPoint, EPUB o texto sin formato. Las exportaciones a LaTeX y Typst conservan la bibliografía y enlazan tus archivos de imagen en lugar de copiarlos, así que mantén esos archivos junto a la exportación. Cuando Pandoc deja algo fuera, la exportación se guarda con advertencias, y **Mostrar las advertencias** enumera lo que se descartó. Usa un ZIP del código para compartir el Markdown original y sus recursos. [Exporta tu trabajo](/docs/export/) trata la secuencia y las comprobaciones que conviene hacer en el archivo convertido.
