Pandoc Word para Markdown: Guia de conversão de linha de comando

Pandoc é a ferramenta de conversão de documentos mais poderosa disponível. Ele converte entre dezenas de formatos, incluindo .docx para Markdown, e dá-lhe um controle fino sobre a saída. Este guia abrange tudo o que você precisa usar Pandoc para Word a Markdown conversão.

O que é o Pandoc?

Pandoc é uma ferramenta de linha de comando livre e de código aberto que converte documentos entre formatos. Suporta mais de 40 formatos de entrada e saída. Para Word para Markdown conversão, Pandoc é o padrão ouro mais configurável do que qualquer ferramenta baseada em navegador, incluindo WordToMD.

Quando usar Pandoc vs. WordToMD:

Instalação Pandoc

Janela

Baixe o instalador do pandoc.org/instalação.html, ou utilizar um gerenciador de pacotes:

# Winget
winget install pandoc

# Chocolatey
choco install pandoc

# Scoop
scoop install pandoc

macOS (em inglês)

# Homebrew
brew install pandoc

# MacPorts
sudo port install pandoc

Linux

# Ubuntu/Debian
sudo apt-get install pandoc

# Fedora
sudo dnf install pandoc

# Arch
sudo pacman -S pandoc

Verificar a instalação:

pandoc --version

Comando de conversão básica

pandoc document.docx -o output.md

É isso. Pandoc deduz o formato de entrada de .docx e o formato de saída de .md.

Versão mais explícita:

pandoc -f docx -t markdown document.docx -o output.md

Opções de formato de saída

Pandoc oferece várias variantes Markdown como saída:

# GitHub Flavored Markdown (GFM)
pandoc document.docx -t gfm -o output.md

# CommonMark
pandoc document.docx -t commonmark -o output.md

# Pandoc's extended Markdown (most features)
pandoc document.docx -t markdown -o output.md

# Standard Markdown (basic)
pandoc document.docx -t markdown_strict -o output.md

GFM é recomendado para a maioria dos casos de utilização (GitHub, Obsidian, GitBook, Notion).

Opções úteis de conversão

Extrair arquivos de mídia

As imagens incorporadas em .docx são extraídas para um diretório:

pandoc document.docx --extract-media=./media -o output.md

Isto salva imagens para ./media/ e adiciona referências de imagem Markdown à saída.

Linhas de envolvimento

Envolvimento da linha de controlo na saída:

# No wrapping (one paragraph = one line)
pandoc document.docx --wrap=none -o output.md

# Wrap at 80 characters
pandoc document.docx --wrap=auto --columns=80 -o output.md

--wrap=none é recomendado para Markdown que será controlado por versão produz diferenças Git mais limpas.

Tabela de Conteúdos

pandoc document.docx --toc -o output.md

Documento independente com metadados

pandoc document.docx -s -o output.md

O -s (standalone) flag gera YAML frontmatter a partir dos metadados do documento.

Conversão por lotes

Converter todos os arquivos .docx num diretório:

PowerShell do Windows

Get-ChildItem -Filter "*.docx" | ForEach-Object {
    $output = [System.IO.Path]::ChangeExtension($_.Name, ".md")
    pandoc $_.FullName -t gfm --wrap=none -o $output
    Write-Host "Converted: $($_.Name) → $output"
}

Bash (macOS/Linux)

for file in *.docx; do
    output="${file%.docx}.md"
    pandoc "$file" -t gfm --wrap=none -o "$output"
    echo "Converted: $file → $output"
done

Para mais opções de conversão por lotes, ver Batch Convert Word para Markdown.

Personalizar a saída com filtros Lua

Pandoc suporta filtros Lua que transformam o documento AST durante a conversão:

pandoc document.docx --lua-filter=my-filter.lua -o output.md

Exemplo de filtro Lua para adicionar um bloco de frontmatter personalizado:

-- add-frontmatter.lua
function Meta(meta)
  meta.draft = false
  meta.author = "WordToMD Team"
  return meta
end

Este é o tipo de personalização que as ferramentas do navegador não podem igualar.

Comparação de Pandoc e mamut.js Produção

WordToMD usa mamut.js debaixo do capô. Pandoc usa o seu próprio parser. Principais diferenças:

Para documentos complexos, Pandoc dá uma saída mais completa. Para documentos simples, WordToMD é mais rápido com configuração zero.

Pandoc Arquivos padrão

Para conversões repetidas com as mesmas configurações, crie um arquivo padrão:

# my-defaults.yaml
from: docx
to: gfm
wrap: none
extract-media: ./media
standalone: true

Então corre:

pandoc document.docx -d my-defaults.yaml -o output.md

Usando Pandoc em CI/CD

Para oleodutos automatizados (GitHub Ações, etc.):

# .github/workflows/convert-docs.yml
- name: Install Pandoc
  run: sudo apt-get install pandoc

- name: Convert Word docs to Markdown
  run: |
    for f in docs/*.docx; do
      pandoc "$f" -t gfm --wrap=none -o "${f%.docx}.md"
    done

FAQ

Pandoc saídas \ Continuações de linha no meu Markdown. Como é que os retiro? Adicionar --wrap=none para desativar o enrolamento de linha dura.

As minhas mesas parecem confusas na saída Pandoc. Tenta . -t gfm para a sintaxe da tabela GFM em vez das tabelas padrão Pandoc Markdown.

As imagens não aparecem na saída. Adicionar --extract-media=./images para extrair imagens incorporadas. Então, faça referência a eles corretamente no seu ambiente alvo.

Pandoc converte citações inteligentes para " Caracteres Como os guardo? Adicionar --no-highlight ou modificar o modelo. Para cotações inteligentes especificamente, elas devem ser preservadas por padrão na maioria dos formatos de saída.

Como são Pandoc e WordToMD comparados para DOCX para Markdown? Ambos funcionam bem para documentos padrão. WordToMD requer configuração zero e produz saída GFM limpa. Pandoc requer instalação, mas lida com documentos complexos (imagens, matemática, comentários, notas de rodapé) de forma mais completa.

Conclusão

Pandoc é a ferramenta mais capaz para Word para Markdown Conversão, especialmente para o processamento por lotes, formatos de saída personalizados e canais CI/CD. Para conversões rápidas e únicas sem instalação, WordToMD Faz o trabalho instantaneamente. Os dois instrumentos complementam-se muito bem.