Pandoc Word a Markdown: Guida di conversione della riga di comando

Pandoc è lo strumento di conversione dei documenti più potente disponibile. Converte tra dozzine di formati, tra cui .docx a Markdown, e ti dà un controllo dettagliato sull'uscita. Questa guida copre tutto ciò che è necessario utilizzare Pandoc per Word a Markdown conversione.

Che cos' è Pandoc?

Pandoc è uno strumento a riga di comando libero e open source che converte documenti tra formati. Supporta oltre 40 formati di input e output. Per la conversione Word a Markdown, Pandoc è lo standard d'oro più configurabile di qualsiasi strumento basato su browser, incluso WordToMD.

Quando usare Pandoc vs. WordToMD:

Installazione Pandoc

Finestre

Scarica l'installazione da pandoc.org/installazione.html, o utilizzare un gestore di pacchetti:

# Winget
winget install pandoc

# Chocolatey
choco install pandoc

# Scoop
scoop install pandoc

macOS

# 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

Verificare l'installazione:

pandoc --version

Comando di conversione di base

pandoc document.docx -o output.md

- E' tutto. Pandoc deduce il formato di input da .docx e il formato di uscita da .md.

Versione più esplicita:

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

Opzioni di formato di uscita

Pandoc offre diverse varianti Markdown come output:

# 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 è raccomandato per la maggior parte dei casi d'uso (GitHub, Obsidian, GitBook, Notion).

Opzioni di conversione utili

Estrarre file multimediali

Le immagini incorporate in .docx vengono estratti in una directory:

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

Questo salva le immagini per ./media/ e aggiunge Markdown riferimenti immagine all'uscita.

Linee di avvolgimento

Avvolgimento della linea di controllo all'uscita:

# 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 è raccomandato per Markdown che sarà controllato dalla versione produce differenze Git più pulite.

Tabella dei contenuti

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

Documento autonomo con metadati

pandoc document.docx -s -o output.md

Il -s (standalone) flag genera YAML frontmatter dai metadati del documento.

Conversione di lotti

Convertire tutti i file .docx in una directory:

Windows PowerShell

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

Per ulteriori opzioni di conversione di lotti, vedere Batch Convertire Word a Markdown.

Personalizzazione dell'uscita con i filtri Lua

Pandoc supporta i filtri Lua che trasformano il documento AST durante la conversione:

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

Esempio di filtro Lua per aggiungere un blocco di materiale di fronte personalizzato:

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

Questo è il tipo di personalizzazione che gli strumenti del browser non possono corrispondere.

Confronto tra Pandoc e mammut.js Output

WordToMD Usa il mammut sotto il cofano. Pandoc utilizza il proprio parser. Principali differenze:

Per documenti complessi, Pandoc fornisce un output più completo. Per documenti semplici, WordToMD è più veloce con impostazione zero.

Pandoc File predefiniti

Per le conversioni ripetute con le stesse impostazioni, creare un file predefinito:

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

Allora corre:

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

Usare Pandoc in CI/CD

Per le condotte automatizzate (GitHub azioni, ecc.):

# .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 uscite \ Continuità di linea nel mio Markdown. Come faccio a rimuoverli? Aggiungere --wrap=none per disattivare l'avvolgimento delle linee rigide.

I miei tavoli sembrano confusi nell'uscita Pandoc. Provaci . -t gfm per la sintassi della tabella GFM al posto delle tabelle predefinite Pandoc Markdown.

Le immagini non appaiono nell'uscita. Aggiungere --extract-media=./images per estrarre immagini incorporate. Quindi riferitevi correttamente all'ambiente di destinazione.

Pandoc converte le citazioni intelligenti in " Come faccio a tenerli? Aggiungere --no-highlight o modificare il modello. Per le smart quotes in particolare, dovrebbero essere conservate per impostazione predefinita nella maggior parte dei formati di uscita.

Come si confrontano Pandoc e WordToMD per DOCX a Markdown? Entrambi funzionano bene per i documenti standard. WordToMD richiede impostazione zero e produce un output GFM pulito. Pandoc richiede l'installazione ma gestisce i documenti complessi (immagini, matematica, commenti, note a piè di pagina) in modo più completo.

Conclusioni

Pandoc è lo strumento più capace per Word in Markdown la conversione, in particolare per la lavorazione a lotti, i formati di uscita personalizzati e le pipeline CI/CD. Per le conversioni rapide e uniche senza installazione, WordToMD fa il lavoro all'istante. I due strumenti si completano bene.