將 DOCX 檔案轉換為 Markdown 是開發人員常見的需求，因為他們希望使用輕量、適合版本控制的文件。 GroupDocs.Conversion Cloud SDK for Java 提供了強大的函式庫，能在伺服器端處理繁重的工作。在本指南中，您將學習如何在 Java 中將 DOCX 轉換為 MD，設定 SDK，逐步瀏覽程式碼，使用 cURL 呼叫 REST API，並微調選項以保持格式完整。

先決條件與設定

在開始之前，請確保您具備以下項目：

  • 已安裝 Java 8 或更高版本。
  • 一個 IDE，例如 IntelliJ IDEA 或 Eclipse。
  • 具有 Client Id 和 Client Secret 的 GroupDocs Cloud 帳戶。
  • 用於相依性管理的 Maven。

使用以下 Maven 依賴將 SDK 添加到您的項目中。您也可以從下載頁面下載最新的 JAR。

<dependency>
    <groupId>com.groupdocs</groupId>
    <artifactId>groupdocs-conversion-cloud</artifactId>
    <version>26.8</version>
</dependency>

配置您的憑證，以便 SDK 能夠對 GroupDocs 雲端進行身份驗證：

Configuration config = new Configuration();
config.setClientId("YOUR_CLIENT_ID");
config.setClientSecret("YOUR_CLIENT_SECRET");

SDK 已就緒後，您可以繼續實作。下一節將逐行說明執行 DOCX 轉 MD 轉換所需的程式碼。

在 Java 中將 DOCX 轉換為 MD：逐步演練

以下是轉換過程的詳細說明。每個步驟對應於從完整範例中取出的簡短程式碼片段。

步驟 1：配置 API 憑證

建立一個 Configuration 物件並提供您的客戶端憑證。

Configuration config = new Configuration();
config.setClientId("YOUR_CLIENT_ID");
config.setClientSecret("YOUR_CLIENT_SECRET");

步驟 2：定義 Markdown 轉換選項

設定來源 DOCX 檔案、目標 MD 檔案，並啟用格式保留。

MarkdownConvertOptions options = new MarkdownConvertOptions();
options.setFilePath("input.docx");
options.setOutputPath("output.md");
options.setPreserveOriginalFormatting(true);

步驟 3：初始化 Conversion API

使用您建立的配置實例化 ConversionApi。

ConversionApi conversionApi = new ConversionApi(config);

步驟 4：建立並發送轉換請求

將選項封裝在 ConvertDocumentRequest 中，然後呼叫轉換方法。

ConvertDocumentRequest request = new ConvertDocumentRequest(options);
ConvertResult result = conversionApi.convertDocument(request);

步驟 5：處理轉換結果

檢查結果並輸出生成的 Markdown 檔案路徑。

System.out.println("Conversion completed successfully. Output file: " + result.getPath());

如需了解所使用類別的更多詳細資訊，請參閱 API 參考。

完整程式碼範例：保留格式的 Markdown 輸出

以下程式碼片段展示了完整且可直接執行的程式，它將 DOCX 檔案轉換為 Markdown，同時保留原始格式。

import com.groupdocs.cloud.conversion.api.ConversionApi;
import com.groupdocs.cloud.conversion.client.Configuration;
import com.groupdocs.cloud.conversion.model.MarkdownConvertOptions;
import com.groupdocs.cloud.conversion.model.ConvertResult;
import com.groupdocs.cloud.conversion.model.requests.ConvertDocumentRequest;

public class DocxToMarkdownExample {
    public static void main(String[] args) {
        // Configure API client (replace with your actual credentials)
        Configuration config = new Configuration();
        config.setClientId("YOUR_CLIENT_ID");
        config.setClientSecret("YOUR_CLIENT_SECRET");

// Initialize Conversion API
        ConversionApi conversionApi = new ConversionApi(config);

// Set conversion options for DOCX → Markdown
        MarkdownConvertOptions options = new MarkdownConvertOptions();
        options.setFilePath("input.docx");          // source DOCX file in storage
        options.setOutputPath("output.md");         // target Markdown file in storage
        options.setPreserveOriginalFormatting(true); // keep formatting where possible

// Create request object
        ConvertDocumentRequest request = new ConvertDocumentRequest(options);

try {
            // Execute conversion
            ConvertResult result = conversionApi.convertDocument(request);
            System.out.println("Conversion completed successfully. Output file: " + result.getPath());
        } catch (Exception e) {
            System.err.println("Conversion failed: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

注意： 此程式碼範例展示了核心功能。在您的專案中使用之前，請確保更新檔案路徑（input.docx、output.md）以符合實際位置，驗證所有必要的相依項已正確安裝，並在開發環境中徹底測試。若遇到任何問題，請參閱官方文件或聯繫支援團隊以獲得協助。

使用 cURL 和 REST API 執行 DOCX 到 MD 轉換

如果您偏好純 HTTP 方法，則可以使用 cURL 命令完成相同的轉換。以下是一個最小工作流程。

首先，取得 OAuth2 存取令牌：

curl -X POST "https://api.groupdocs.cloud/v2.0/oauth2/token" \
     -H "Content-Type: application/json" \
     -d '{"client_id":"YOUR_CLIENT_ID","client_secret":"YOUR_CLIENT_SECRET","grant_type":"client_credentials"}'

假設回應中包含 "access_token":"YOUR_ACCESS_TOKEN"，上傳 DOCX 檔案：

curl -X PUT "https://api.groupdocs.cloud/v2.0/storage/file/input.docx" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/octet-stream" \
     --data-binary @input.docx

curl -X POST "https://api.groupdocs.cloud/v2.0/conversion/convert" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
           "outputPath":"output.md",
           "format":"MD",
           "preserveOriginalFormatting":true,
           "filePath":"input.docx"
         }'

最後，下載生成的 Markdown 檔案：

curl -X GET "https://api.groupdocs.cloud/v2.0/storage/file/output.md" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -o output.md

欲取得完整的參數清單，請參閱官方 API 文件。

微調 DOCX 到 MD 的轉換選項

SDK 提供多個選項，您可以調整以控制輸出。

  • PreserveOriginalFormatting - 保留標題、清單、表格以及其他樣式。
options.setPreserveOriginalFormatting(true);
  • OutputPath - 定義 Markdown 檔案在雲端儲存中的存放位置。
options.setOutputPath("output.md");
  • 自訂 Markdown 設定 - 您可以透過 MarkdownConvertOptions 的其他屬性調整換行、程式碼區塊處理等（請參閱 API 參考）。

請嘗試這些設定，以匹配您在最終 MD 檔案中所需的精確外觀。

DOCX 轉換為 MD 的效能考量

在轉換大量文件或大型檔案時，請記住以下提示：

  1. 重用 ConversionApi 實例 - 只建立一次客戶端並重複使用，可避免重複的驗證開銷。
  2. 串流檔案而非將整個文件載入記憶體 - SDK 支援大型 DOCX 檔案的串流，降低堆積使用量。
  3. 批次上傳 - 在可能的情況下一次請求上傳多個 DOCX 檔案，然後在迴圈中觸發轉換。
  4. 調整併發度 - 使用執行緒池平行執行多個轉換，但需監控 API 的速率限制。

應用這些做法將有助於您有效擴展 DOCX 到 MD 的工作流程。

結論

在 Java 中將 DOCX 轉換為 MD 非常簡單，只需使用 GroupDocs.Conversion Cloud SDK for Java。按照設定步驟、使用提供的程式碼範例，或透過 cURL 呼叫 REST API，即可在保留格式的同時自動化文件流程。請記得檢查授權選項；SDK 採用商業授權，您也可以從臨時授權頁面取得評估用的臨時授權。立即開始整合 DOCX 到 MD 的轉換，簡化您的內容工作流程。

常見問題

如何在 Java 中將 DOCX 轉換為 MD 而不失去格式？
在 MarkdownConvertOptions 中將 preserveOriginalFormatting 設置為 true。SDK 會嘗試在轉換過程中保持標題、表格和列表的完整性。

是否可以在一次執行中將多個 DOCX 檔案轉換為 MD？
是的。遍歷您的檔案清單，重複使用相同的 ConversionApi 實例，並對每個檔案調用 convertDocument。此方法可減少開銷並加快批量處理速度。

REST API 在 DOCX 轉換為 MD 時需要哪種驗證方法？
API 使用 OAuth2 client‑credentials 流程。使用您的 client ID 和 secret 獲取存取令牌，然後在所有後續呼叫的 Authorization: Bearer 標頭中包含該令牌。

我可以自訂 Markdown 輸出樣式（例如程式碼區塊、項目符號字符）嗎？
MarkdownConvertOptions 類別公開多個屬性以微調 Markdown 語法。請參閱 API reference 以取得可配置選項的完整清單。

Read More