若要在 Mac「捷徑」中讀取本機 Markdown 檔案的內容，請先將檔案輸入轉換為文字再使用。用一次性樣本檢查結果；如果轉換失敗，請用 cat 讀取檔案，並將其內容傳送至捷徑。

本指南說明如何在 Finder 中選取一個本機 Markdown 檔案，並顯示其原始文字內容，包括標題標記和清單標點。關鍵在於區分三件事：所選檔案、檔案路徑，以及檔案中儲存的文字。

為什麼捷徑收到的是檔案，而不是檔案中的文字？

Finder 提供的是檔案輸入。Apple 將「檔案」和「文字」定義為「捷徑」中不同的輸入類型：檔案可以是任何類型的文件，而文字則是未套用格式的純文字。因此，接受 Markdown 檔案本身並不能確定下一個動作收到的是文字形式的檔案內容。在 Mac 上的「捷徑」中了解輸入類型。

當動作需要轉換類型時，「捷徑」會使用內容圖表進行轉換。Apple 也說明了一項明確的控制方式：按一下變數標記並更改其「類型」。這種轉換不同於選取檔案名稱等屬性。名稱或路徑仍然只是檔案的描述。內容圖表引擎、在 Mac 上的「捷徑」中調整變數。

Apple 引用的指南說明了轉換機制，但並未保證所有副檔名為 .md 的檔案都會轉換成其原始文字。請將轉換視為需要用已知內容驗證的步驟。如果原生轉換沒有產生預期文字，以下命令列方法會提供明確的檔案讀取方式。

建立內容已知的一次性 Markdown 檔案

使用這個合成測試檔，避免把檔名誤認為成功讀取。將完整設定內容貼到終端機。它會建立新的暫存目錄、寫入一個範例檔案，並在 Finder 中開啟該目錄。

demo_dir=$(/usr/bin/mktemp -d /tmp/markdown-shortcuts.XXXXXX) &&
printf '%s\n' '# Sample board' '' '- Blue square' '- Green circle' > "$demo_dir/sample.md" &&
/usr/bin/open "$demo_dir"

預期的檔案內容如下：

# Sample board

- Blue square
- Green circle

-d 選項會告訴 mktemp 建立目錄，而結尾的 X 字元會讓它選擇唯一名稱。因此，每次成功執行設定都會建立一個新的目錄。如果建立失敗，&& 串接會阻止後續命令執行。Apple 提供相關的 mktemp 手冊。

printf 命令會寫入合成的文字行，包括空白行。它的輸出重新導向會在新目錄中建立 sample.md。一般的 > 重新導向可能會覆寫現有檔案，因此請保留這份設定，不要把目的地改成現有文件。這個範例透過新目錄避免名稱衝突。Apple 的 printf 手冊、Shell 輸入與輸出。

建立明確要求文字內容的 Finder 捷徑

建立一個名為 Read Markdown Text 的捷徑。Apple 說明了如何使用工具列的新增按鈕建立捷徑、為其命名，以及從動作資料庫加入動作。在 Mac 上建立自訂捷徑。

設定 Finder 入口點：

  1. 開啟捷徑的「詳細資訊」面板。
  2. 啟用「用作快速動作」，並選取「Finder」。
  3. 在編輯器頂端的輸入區塊中，允許「檔案」和「文字」。檔案支援 Finder 工作流程；文字則支援下方的終端機備用方法。
  4. 對於缺少輸入的情況，選擇「停止並回應」，並輸入「選取一個範例 Markdown 檔案。」

Apple 說明了 Finder 選項，並指出可能需要檔案或資料夾輸入才能啟用此選項。其輸入設定也支援在沒有收到輸入時停止並回應。在 Mac 上工作時執行捷徑、限制捷徑的輸入。

接著加入內容處理動作：

  1. 加入「文字」動作。
  2. 在文字欄位中只放入「捷徑輸入」變數。
  3. 按一下該變數標記，開啟「類型」選單，然後選取「文字」。請勿選取檔名屬性。
  4. 在「文字」動作之後加入「快速預覽」，並使用「文字」動作的輸出。

明確的變數轉換會在使用輸入時要求將其轉成文字。後續「文字」動作的輸出就是之後文字處理步驟要使用的值。Apple 說明了如何透過變數編輯器更改變數類型。在 Mac 上的「捷徑」中調整變數。

若要確認已安裝版本的行為，請按住 Control 鍵並按一下動作圖像，然後選擇「顯示資訊」。Apple 說明這是檢查動作接受的輸入和產生的輸出的方法。調整包含多個檔案和文字變數的現有捷徑時，這項資訊特別有用。在 Mac 上的「捷徑」中瀏覽動作列表。

在 Finder 中，只選取 sample.md，按住 Control 鍵並按一下它，然後依序選擇「快速動作」和「Read Markdown Text」。Apple 說明了這種執行方式。如果找不到捷徑，請先檢查 Finder 設定和接受的輸入類型。在 Mac 上工作時執行捷徑。

成功的結果會包含 # Sample board 和兩個清單項目。只看到 sample.md 或其目錄路徑並不算通過此檢查。Apple 建議在動作之間放入「快速預覽」，檢查捷徑中傳遞的內容。在 Mac 上測試「捷徑」中的動作。

如果轉換失敗，請先讀取內容再呼叫「捷徑」

使用終端機明確執行讀取操作。Apple 的終端機指南指出，cat 可用來檢視文字檔案的內容。其「捷徑」命令列指南區分了使用 -i 提供的檔案輸入，以及透過管線提供的文字。在 Mac 的終端機中檢視文字檔案、從命令列執行捷徑。

以下內容是前述設定範例的延續，不是獨立程式。設定成功後，請在同一個終端機分頁執行，並確認捷徑已以 Read Markdown Text 這個確切名稱儲存：

(
    set -o pipefail

    if [ -f "$demo_dir/sample.md" ] && [ -r "$demo_dir/sample.md" ]; then
        /bin/cat "$demo_dir/sample.md" |
            /usr/bin/shortcuts run "Read Markdown Text"
    else
        printf '%s\n' 'The example file is missing or unreadable.' >&2
        exit 1
    fi
)

在此，cat 會讀取檔案並將其內容寫入標準輸出。管線會將這些內容傳送至捷徑。將路徑加上引號，可確保它作為單一引數傳入。-f 和 -r 檢查會要求檔案存在、屬於一般檔案且可讀取。命令列入門、Apple 的 test 手冊。

括號會將 Shell 選項的變更限制在此命令群組中。pipefail 會讓管線階段失敗反映在群組的結束狀態中。前置檢查無法保證稍後讀取時檔案仍可存取；如果 cat 遇到讀取錯誤，請檢查該錯誤，不要將不完整的預覽當作完整內容。

此備用方法會將捷徑收到的內容從檔案改為文字。它不會重新命名 Markdown 檔案，也不會建立轉換後的文件。現有的「文字」和「快速預覽」動作可以檢查收到的文字。

以下三種命令形式的含義各不相同：

命令形式 捷徑收到的內容
shortcuts run "Read Markdown Text" -i "$demo_dir/sample.md" 檔案輸入；仍需在捷徑中進行轉換。
printf '%s\n' "$demo_dir/sample.md" | shortcuts run "Read Markdown Text" 以文字形式傳入的路徑。
cat "$demo_dir/sample.md" | shortcuts run "Read Markdown Text" 透過標準輸入傳入檔案內容。

此表說明了 Apple 文件中提到的差異：使用 -i 傳入檔案路徑，以及透過管線傳入文字。管線前的操作會決定該文字是路徑還是文件內容。從命令列執行捷徑。

加入更多動作之前，先判斷結果

使用已知的測試檔判斷需要修正的地方：

  • 只顯示檔名： 檢查變數是否擷取了名稱屬性，而不是要求文字內容。
  • 只顯示路徑： 檢查命令是否只輸出路徑，而沒有讀取檔案。
  • 原生轉換失敗，但終端機方法可行： 在此工作流程中使用明確的讀取方法；只更改輸入標籤並不能解決轉換問題。
  • 未收到輸入： 從 Finder 中選取的檔案或文件說明的終端機命令執行。從 Dock 啟動捷徑不會自動提供所選檔案。
  • 原始內容為空白： 與測試檔比對。有效的空檔案和不存在的檔案是不同情況。

Apple 分別說明了變數屬性和內容類型轉換，並指出從 Dock 啟動的捷徑可能不會收到初始輸入。這些差異有助於在修改後續動作之前找出問題。在 Mac 上的「捷徑」中調整變數、限制捷徑的輸入。

測試時，請將工作流程限制在一個小型本機文字檔。選取多個檔案時，還需要另外決定要逐一處理每個檔案，還是合併其內容。此範例能取得可讀取的原始文字；它不是逐位元組複製檔案的程序。

預覽中出現預期的標題和清單行後，請將後續文字處理動作連接到「文字」動作的輸出。等整條流程正常運作後，再移除一次性目錄。最重要的檢查點很簡單：下一個動作必須收到你已確認的文件內容。

來源