Importar Markdown
Tem uma pilha de textos escritos de outra ferramenta, arquivos .md simples (uma exportação de site estático, um CMS anterior ou uma pasta de notas)? A tela Importar Markdown os transforma em páginas ou posts em rascunho em um único lote: envie, revise, publique. Nada é publicado automaticamente: todo arquivo importado chega como um rascunho comum, exatamente como se você o tivesse digitado.
Iniciando uma importação
- Na administração, vá a uma lista de Pages ou Posts e abra Importar Markdown (páginas e posts têm cada um sua própria rota;
typedefine o alvo). - Defina o idioma padrão do lote.
- Selecione até 100 arquivos
.md/.markdownde uma vez (lote inteiro com até 40 MiB). - Envie.
Se os módulos opcionais de conversão não estiverem instalados no seu servidor, o formulário avisa antes de você escolher um único arquivo, e a importação falha com "peça a um administrador que os instale": ela nunca falha silenciosamente no meio do lote.
Front matter
Cada arquivo pode começar com um bloco opcional de cabeçalho YAML ---:
---
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…
---Regras de fallback tornam o front matter opcional:
- Título: o
titledo front matter → o primeiro# headingdo documento (removido do corpo para não aparecer duas vezes) → o nome do arquivo. - Slug: o
slugdo front matter → uma versão limpa do título → o nome do arquivo limpo, com sufixos automáticos (-2,-3…) se dois arquivos cairiam no mesmo endereço. - Tags: uma string separada por vírgulas ou uma lista YAML, ambas funcionam.
Regras que se aplicam quando você inclui um cabeçalho:
- Mantenha-o plano: apenas as chaves acima. Uma lista aninhada sob
title:é rejeitada com o campo nomeado. language:precisa ser um idioma que o seu site realmente tenha configurado, e um que a sua conta tenha permissão de escrever, verificado por arquivo.- Um valor de
date:/published_at:é aceito emYYYY-MM-DDsimples ou com hora; uma verificação de calendário real rejeita mês 13, dia 45, etc. Uma data sem sentido não faz o arquivo falhar; ela é apenas ignorada. - Sem agendamento: as datas do front matter são registradas apenas como metadados do item; a publicação continua sendo uma decisão manual/de revisão. Isso é explícito no código ("auto-scheduling ruled out"), então nada entra no ar inesperadamente.
O que você recebe de volta
- Todos os arquivos se tornam rascunhos: nada é publicado por uma importação, jamais.
- O markdown do corpo converte para o mesmo HTML que o seu editor escreve, incluindo converter um
# headingremanescente um nível abaixo para umH2, já que a estrutura de títulos do editor começa no H2. - Um rebuild do site acontece automaticamente se pelo menos um rascunho foi criado (esses rascunhos existem no CMS imediatamente; apenas a publicação deles espera por você).
- A tela de resultados é por arquivo: cada rascunho criado com seu link de edição e o arquivo de onde veio, e cada falha com seu erro preciso.
Quais falhas você pode ver
Todo problema é reportado por nome de arquivo, em linguagem simples:
| Mensagem | Causa |
|---|---|
| “not a .md/.markdown file” | O arquivo não tinha a extensão correta |
| “file is empty” | Upload de tamanho zero |
| “invalid YAML front matter (…)” | O cabeçalho --- existe mas não faz parse |
| “front matter must be a YAML mapping…” | O cabeçalho não é pares chave/valor |
| “front matter field ‘<x>’ must be plain text, not a nested list/mapping” | YAML aninhado onde uma string simples pertence |
| “could not determine a title (empty file/filename)” | Tudo o que a cadeia de fallback podia tentar estava vazio |
| “title exceeds 500 characters” | Título longo demais |
| “could not derive a slug from the title or filename” | Ambas as fontes resultaram em nada utilizável |
| “markdown conversion failed (…)” | O documento não fez parse como Markdown |
| “language ‘…’ is not configured” / “not authorised for language ‘…’” | O language: do arquivo (ou o padrão do lote) não é um idioma em que você possa escrever |
| “database error: check the server log” | A escrita em si falhou: tente o arquivo de novo |
Falhas por arquivo nunca derrubam o lote: arquivos válidos continuam sendo importados enquanto os inválidos reportam.
Boas práticas
- Traga suas imagens separadamente: as URLs de imagem no corpo são importadas verbatim; a jogada prática é enviar as imagens para a biblioteca de mídia primeiro e referenciá-las no Markdown, para que os rascunhos já apontem para URLs funcionais antes de você entrar no ar.
- Deixe os títulos fazerem os slugs: se dois arquivos do lote colidiriam, o importador sufixa para você; sobrescrever slugs é feito com o
slug:do front matter apenas onde importa. - Formate sem dor: aceite o título por fallback de H1 apenas como último recurso; escrever
title:no front matter mantém as páginas iniciais limpas. - Verifique colunas e rascunhos um a um; a tela de resultados linka cada rascunho imediatamente após a importação para uma passagem de revisão.
A versão curta
Uma pasta de Markdown se torna uma pasta de rascunhos em uma única requisição: um YAML opcional define título, slug, categoria/tags, idioma e metadados; todo o resto é derivado; nada é publicado automaticamente; a tela de resultado por arquivo é a sua lista de verificação do que precisa de uma olhada antes de entrar no ar.