Hecho con Chinaski

Importar Markdown

¿Tienes un montón de escritos de otra herramienta: archivos .md planos (una exportación de sitio estático, un CMS anterior o una carpeta de notas)? La pantalla Import Markdown los convierte en páginas o posts en borrador en un solo lote: subir, revisar, publicar. Nada se publica automáticamente: cada archivo importado llega como un borrador ordinario, exactamente como si lo hubieras tecleado tú.

Iniciar una importación

  1. En el admin, ve a una lista de Pages o Posts, y abre Import Markdown (páginas y posts tienen cada uno su propia ruta; type define el destino).
  2. Define el idioma predeterminado del lote.
  3. Selecciona hasta 100 archivos .md/.markdown a la vez (lote completo de hasta 40 MiB).
  4. Sube.

Si los módulos de conversión opcionales no están instalados en tu servidor, el formulario te lo avisa antes de que elijas un solo archivo, y la importación falla con “pide a un admin que los instale” : nunca falla en silencio a mitad del lote.

Front matter

Cada archivo puede comenzar con un bloque de encabezado YAML --- opcional:

---
title: My First Post
slug: my-first-post
language: en
category: News
tags: [announcements, tips]
date: 2024-03-14
meta_title: My First Post | Example Site
meta_description: A short searchable summary…
---

Las reglas de respaldo hacen que el front matter sea opcional:

  • Título: title del front matter → el primer # heading del documento (eliminado del cuerpo para que no aparezca dos veces) → el nombre del archivo.
  • Slug: slug del front matter → una versión limpia del título → el nombre del archivo limpiado : con duplicados automáticos (-2, -3…) si dos archivos caerían en la misma dirección.
  • Tags: una cadena separada por comas o una lista YAML, ambas funcionan.

Reglas que aplican cuando sí incluyes un encabezado:

  • Mantenlo plano: solo las claves de arriba. Una lista anidada bajo title: se rechaza con el campo nombrado.
  • language: debe ser un idioma que tu site realmente tenga configurado, y uno que tu cuenta pueda escribir : se verifica por archivo.
  • Un valor de date:/published_at: se acepta en formato simple YYYY-MM-DD o con hora; una verificación de calendario real rechaza mes 13, día 45, etc. Una fecha sin sentido no hace fallar el archivo: simplemente se ignora.
  • Sin programación: las fechas del front matter se registran solo como metadatos del elemento : la publicación sigue siendo una decisión manual/de revisión. Esto es explícito en el código (“auto-scheduling ruled out”), así que nada sale en vivo inesperadamente.

Qué obtienes de vuelta

  • Todos los archivos se convierten en borradores: nada es publicado por una importación, jamás.
  • El markdown del cuerpo se convierte al mismo HTML que escribe tu editor: incluyendo convertir un # heading sobrante un nivel abajo a un H2, ya que la estructura de headings del editor comienza en H2.
  • Un build del site ocurre automáticamente si se creó al menos un borrador (estos borradores existen en el CMS de inmediato; solo su publicación te espera a ti).
  • La pantalla de resultados es por archivo: cada borrador creado con su enlace de edición y el archivo del que proviene, y cada fallo con su error preciso.

Qué fallos puedes ver

Cada problema se reporta por nombre de archivo, en lenguaje claro:

Mensaje Causa
“not a .md/.markdown file” El archivo no tenía la extensión correcta
“file is empty” Subida de longitud cero
“invalid YAML front matter (…)” El encabezado --- existe pero no se analiza
“front matter must be a YAML mapping…” El encabezado no son pares clave/valor
“front matter field ‘’ must be plain text, not a nested list/mapping” YAML anidado donde corresponde una cadena simple
“could not determine a title (empty file/filename)” Todo lo que la cadena de respaldo pudo intentar estaba vacío
“title exceeds 500 characters” Título demasiado largo
“could not derive a slug from the title or filename” Ambas fuentes resultaron en nada utilizable
“markdown conversion failed (…)” El documento no se analizó como Markdown
“language ‘…’ is not configured” / “not authorised for language ‘…’” El language: del archivo (o el predeterminado del lote) no es un idioma en el que puedas escribir
“database error : check the server log” La escritura en sí falló: reintenta el archivo

Los fallos por archivo nunca derriban el lote: los archivos válidos siguen importándose mientras los inválidos reportan.

Buenas prácticas

  • Trae tus imágenes por separado: las URLs de imagen en el cuerpo se importan tal cual : el movimiento práctico es subir las imágenes a la biblioteca de medios primero y referenciarlas desde el Markdown, así los borradores ya apuntan a URLs que funcionan antes de que salgas en vivo.
  • Deja que los títulos hagan los slugs: si dos archivos del lote colisionarían, el importador añade sufijos por ti; sobrescribir slugs se hace con el slug: del front matter solo donde importa.
  • Formato sin dolor: acepta el título por respaldo del H1 solo como último recurso; escribir title: en el front matter mantiene las páginas iniciales limpias.
  • Verifica columnas y borradores una por una : la pantalla de resultados enlaza cada borrador inmediatamente después de la importación para una pasada de revisión.

La versión corta

Una carpeta de Markdown se convierte en una carpeta de borradores en una sola solicitud: un YAML opcional define título, slug, categoría/tags, idioma y metadatos; todo lo demás se deriva; nada se publica automáticamente; la pantalla de resultados por archivo es tu lista de verificación de lo que necesita una mirada antes de salir en vivo.

Lee este sitio en