一個目錄樹產生器，會把每一行一個完整的相對檔案路徑，轉換成一棵渲染出來的文字樹狀結構，其根節點是一個點，父目錄則是從共同的前綴推論出來的。整個過程都在本機完成：你貼上路徑、選擇你所使用的分隔符號樣式（正斜線或反斜線）、選擇 Unicode 或 ASCII 連接符號，這個工具就會回傳一棵具確定性的樹狀結構，讓你複製貼到 README、工單，或設計文件裡。因為驗證、排序與渲染，全部都在目前的瀏覽器分頁中完成，你貼上的檔案名稱與專案結構，絕不會離開你的裝置。輸出結果在所有支援的瀏覽器上都完全一致，因為名稱的排序，是依照 UTF-16 碼元比較來決定的，而不是依照語系、檔案系統，或輸入順序。嚴格的驗證機制，正是這種確定性值得信賴的原因。這個產生器會拒絕絕對路徑、磁碟機根目錄、混用的分隔符號、空白區段、點區段、父層回溯、重複路徑，以及檔案／目錄衝突，而不是默默地重寫它們；確切的限制是輸入內容最多 100,000 個 UTF-16 碼元、最多 2,000 行路徑、每個路徑最多 128 個區段、每個區段最多 255 個碼元，以及渲染輸出最多 500,000 個碼元，只要超過任何一項邊界的下一個碼元、條目、區段，或輸出字元，就會被拒絕，並顯示指出問題所在行號的錯誤訊息。
從一份路徑清單，變成一棵視覺化的樹狀結構
一棵目錄樹，能把扁平羅列的檔案清單，變成讀者一眼就能掃過去理解的結構。大多數開發者需要用到樹狀結構的時候，通常是要傳達一個模組的形狀、為一份錯誤報告附上佐證，或是在還沒寫任何程式碼之前，先勾勒出一個新套件的版面配置。要得到這棵樹，最快的做法通常是一行殼層指令，但殼層指令假設你對想要輸出的資料夾有讀取權限，而且它們經常會把結構與檔案內容混在一起，或是仰賴一個可能無法渲染方框繪製字元的終端機。
以瀏覽器為基礎的產生器，走的是不同的路線。你提供一份相對路徑清單，這個工具會把它們解讀成記憶體中的一棵前綴樹，然後把渲染結果，以純文字的形式回傳給你。這份清單可以來自任何地方：貼上的 find 指令輸出、從檔案管理員複製下來的目錄清單、CSV 匯出檔，或是手寫的一份提議版面配置草稿。唯一的結構性限制，是每一行都必須是一個完整的相對路徑，而且所有行都必須使用相同的分隔符號樣式。
準備你的路徑清單
這棵樹的品質，取決於輸入內容的品質。在貼上之前，先過一遍四個小檢查項目，就能抓出大多數會被拒絕的情況。
第一，確認每一行都是一個完整的相對檔案路徑。當一個路徑沒有開頭的分隔符號，也沒有磁碟機根目錄時，它就是相對路徑。src/lib/parser.ts 是相對路徑；/src/lib/parser.ts 與 C:\src\lib\parser.ts 則不是。這個產生器會把絕對路徑與磁碟機根目錄形式，當成錯誤處理，而不是默默地重寫它們。
第二，決定這份清單使用哪一種分隔符號樣式，並全程保持一致。正斜線是通用的預設樣式，符合 Unix、macOS 與大多數現代開發工具的慣例。反斜線則常見於 Windows 原生路徑，例如 src\lib\parser.ts。在同一次執行中，混用 src/lib/parser.ts 與 src\lib\parser.ts 會被拒絕，因為工具無法判斷在任何一個位置，原本想使用的是哪一種分隔符號。
第三，移除多餘的空白行、開頭或結尾的空白字元，以及從 Windows 貼上內容時殘留的任何歸位字元。單獨的歸位字元，會被視為 ASCII 控制字元，空白行則會被視為空路徑；這兩者都無法通過驗證。
第四，確保每一個名稱代表的是一個檔案，而不是一項目錄宣告。清單中先出現 src，接著出現 src/index.ts，這是一個明確的檔案／目錄衝突，因為第一行說有一個名為 src 的檔案，第二行卻說有一個名為 src 的目錄。如果你想要的是一個目錄，就列出它裡面的一個檔案；父目錄會從前綴推論出來。
用三個步驟產生這棵樹
打開 Directory Tree Generator，依照三個明確的步驟操作。
- 在輸入框中貼上內容，每一行一個完整的相對檔案路徑。確認每一行都使用相同的分隔符號樣式，且整份清單中沒有空白行、多餘的歸位字元、開頭的分隔符號、磁碟機根目錄、點區段，或混用的分隔符號。
- 選擇與你的輸入內容相符的分隔符號（正斜線或反斜線），以及輸出樣式（Unicode 或 ASCII 連接符號）。分隔符號設定是嚴格的；輸入內容中任何位置出現相反的分隔符號，都會被拒絕，而不是被默默轉換。
- 選擇 Generate tree。頁面會清除任何先前的樹狀結構或錯誤訊息，依照明確的限制驗證這份清單，從一個點開始渲染出這棵樹，並顯示建立的節點數量。用 Copy 動作複製渲染出來的輸出結果；如果剪貼簿權限無法使用，也可以手動選取文字。
一次成功的執行，會回報節點數量與渲染出來的樹狀結構。如果輸入內容超過 2,000 行、100,000 個 UTF-16 碼元、每個路徑 128 個區段，或每個區段 255 個碼元，就會回報出問題的那一行，並移除先前成功產生的樹狀結構，確保畫面上不會殘留過時的內容。一次失敗的產生過程，絕不會在頁面上留下較舊、曾經成功的樹狀結構。
在 Unicode 與 ASCII 輸出之間做選擇
這個產生器提供兩種連接符號樣式，產生出來的結構相同，但呈現方式不同。這項選擇純粹是外觀上的，不會影響排序、驗證，或推論出來的目錄階層。
| 面向 | Unicode 模式 | ASCII 模式 |
|---|---|---|
| 分支連接符號 | ├── and └── | |-- and `-- |
| 垂直導引線 | │ | | |
| 最適合的環境 | 現代編輯器、網頁文件、支援 UTF-8 的終端機 | 純文字環境、不支援 UTF-8 的終端機、複製貼上到舊系統中 |
| 視覺密度 | 緊湊，在 Markdown 渲染中容易辨識 | 稍微寬一些，完全由鍵盤字元組成 |
| 排序方式與結構 | 與 ASCII 完全相同 | 與 Unicode 完全相同 |
切換連接符號樣式，本身並不會重新產生這棵樹。設定一改變，頁面就會立刻清除現有的輸出結果，並等待你重新執行一次 Generate tree 動作，因此你看到的輸出結果，永遠反映的是目前分隔符號與連接符號設定的組合。
為什麼這個產生器會拒絕含糊不清的輸入
嚴格的驗證，是一個具確定性的產生器的核心所在。這個工具會拒絕任何可能對同一份輸入產生兩棵不同樹狀結構的內容，也會拒絕任何可能在你不知情的情況下，悄悄改變路徑意義的內容。最常見的拒絕原因，可以歸納成一份簡短的清單。
| 輸入內容包含什麼 | 為什麼會被拒絕 |
|---|---|
| 混用的分隔符號（例如 src/lib\parser.ts） | 分隔符號設定是嚴格的，相反的分隔符號不會被猜測或取代。 |
| 因重複或結尾的分隔符號而產生的空白區段（src//index.ts、src/） | 空白區段不會被正規化移除。 |
| 點區段或父層區段（./src/index.ts、../index.ts） | 這個產生器不會重寫回溯路徑。 |
| 絕對路徑或磁碟機根目錄（/home/user/src/index.ts、C:\src\index.ts） | 必須是相對路徑。 |
| 重複的路徑 | 默默去除重複項目，會改變輸入內容的意義。 |
| 檔案／目錄衝突（src 加上 src/index.ts） | 同一行，不能有時候代表檔案，有時候又代表目錄。 |
| ASCII 控制字元，包括單獨的歸位字元 | 它們可能會把終端機輸出切開，或讓渲染出來的樹狀結構產生誤導。 |
| 空白行，包括結尾的空白行 | 空路徑不是一個合法的檔案路徑。 |
每一次拒絕，都會指出具體的行。這個工具不會跳過有問題的行、回傳一棵部分的樹狀結構，或為了符合配額而截斷名稱、區段，或輸出內容。限制是明確的：輸入內容最多 100,000 個 UTF-16 碼元、最多 2,000 行路徑、每個路徑最多 128 個區段、每個區段最多 255 個碼元，渲染輸出最多 500,000 個碼元。恰好等於邊界值的內容會被接受；超過這個邊界的下一個碼元、條目、區段，或輸出字元則不會。
產生出來的樹狀結構，適合放進你工作流程的哪個位置
- README 與新人上手： 在 README 最上方放一棵簡短的樹狀結構，能讓新加入的貢獻者在幾秒鐘內掌握專案的形狀。因為這個產生器是依照 UTF-16 碼元排序，而不是依照輸入順序，所以你可以重新排列來源清單，而不會改變渲染出來的結果，這讓這棵樹在多次編輯之間都能維持穩定。
- 問題回報與錯誤工單： 當一份錯誤報告需要列出涉及的確切檔案時，貼上一棵樹狀結構，會比一份文字敘述的清單更精簡，也更不容易被誤解。審查者可以一眼看出某個路徑屬於哪一個模組，以及哪些葉節點是兄弟關係。
- 程式碼審查與提交請求說明： 一棵針對變動檔案產生的樹狀結構，能在不牽扯進無關目錄的情況下，概述這次的變更。因為重複的路徑會被拒絕，這份清單本身，就記錄了這次變更中所有獨立的檔案。
- 架構筆記與設計備忘錄： 架構筆記，特別受益於與提議版面配置完全吻合的樹狀結構。嚴格的驗證機制，能抓出文字敘述與清單之間的任何落差，因為這個產生器拒絕渲染不一致的輸入內容。
- 客服與客戶訊息： 當一位客服工程師需要確認客戶的目錄配置時，由一份簡短路徑清單產生出來的樹狀結構，能透過聊天訊息、工單表單與電子郵件順利傳遞，而不會洩漏檔案內容。這個產生器絕不會檢查本機資料夾，因此由客戶自己確切掌控要分享哪些路徑。
對於在貼上內容之前，先透過命令殼層收集路徑的 Windows 使用者，CMD walkthrough for directory trees 涵蓋了同一項任務在命令列端的做法。Linux 與 macOS 使用者，則可以在 Linux path-list guide 中找到對應的殼層管線做法。
相同的清單、相同的設定，加上相同的瀏覽器環境，每一次都會產生出相同的樹狀結構，因此今天產生的一棵樹，即使同事明天用一份稍微重新排序過的來源清單重新產生一次，結果依然會維持穩定。正是這種確定性，讓目錄樹產生器成為一種實用的文件撰寫基本元件：貼上、產生、複製，等版面配置改變時再貼一次。