简体中文 | English

md-tree-updater 🌳

A tool to automatically generate and update a project directory tree in your Markdown files.

🤖 Note on AI Generation

This script was generated with the assistance of AI, and all English documentation was also generated by AI.

What Problem Does This Solve?

• You love to add descriptions for each file/folder in the generated directory tree.
• You're tired of manually updating the project structure tree in README.md every time you add or delete files.

✨ Features

• Directory Tree: Generates a directory tree based on your file structure.
• Description-Driven: Descriptions are maintained in a separate tree-descriptions.yml file, so they persist even when the tree changes.
• Smart Sync: Automatically discovers new files and adds entries for them in the descriptions file.
• Flexible Ignoring: Configure complete ignore (fully hidden) or shallow ignore (show folder name but not its contents).
• Logical Sorting: Ensures the display order is consistent with common file explorers.
• Injection Mode: Uses <!-- TREE_START --> and <!-- TREE_END --> tags to precisely update the tree at a specific location in your Markdown file.

🛠️ Prerequisites

This tool is built on Node.js. Before running, please ensure you have [Node.js] installed.

You can check if it's installed correctly by running the following commands in your terminal:

node -v
npm -v

🚀 Usage

This project is a "template" that you can use directly, not an NPM package to be installed. Please follow these steps to integrate this tool into your existing project.

1. Copy the Files

Copy the downloaded md-tree-updater.mjs and tree-config.mjs files into a scripts folder in your project's root directory.

For clarity, we'll assume you've placed them in your-project/scripts/.

2. Install Dependencies

In the root directory of your project (your-project), open a terminal and run the following command to install the dependencies required by this script. This will add them to your own package.json.

npm install directory-tree js-yaml --save-dev

3. Register the Script Command

Open the package.json file in your project's root directory and add a new command to the "scripts" field:

"scripts": {
  "//": "Your other scripts...",
  "tree:update": "node scripts/md-tree-updater.mjs"
},

Note: Ensure the path after node matches the actual location where you placed md-tree-updater.mjs in step 1.

4. Run It!

In the root directory of your project (your-project), run the following command to use the tool:

npm run tree:update

First-time use: The script will automatically generate the necessary configuration files and the target Markdown file based on tree-config.mjs. To avoid any issues, we recommend editing tree-config.mjs to your liking before running the script for the first time.

Configuration Files Explained

Your final project structure will include the following files:

your-project/
├─ scripts/
│  ├─ md-tree-updater.mjs
│  └─ tree-config.mjs
├─ README.md
├─ .treeignore
└─ tree-descriptions.yml

---

1. The Main Script: md-tree-updater.mjs

This is the core script file that executes all the logic.

2. The Main Configuration File: tree-config.mjs

Configure the paths for other files here. The main script will work and generate files based on this configuration.

export const config = {
  root: '.', // Your root directory, usually no need to change.
  targetFile: 'README.md', // The Markdown file to which the tree will be added.
  descriptionsFile: 'tree-descriptions.yml', // Add descriptions for the tree here.
  ignoreFile: '.treeignore', // The ignore rules file.
};

3. The Ignore File: .treeignore

Configure ignore rules here. There are two types of rules: rules ending with a "/" are for shallow ignoring.

Rule Syntax	Effect	Description
node_modules/	Shallow Ignore	The folder itself will appear in the tree, but all of its contents will be hidden.
.git	Complete Ignore	The file or directory will be completely hidden from the tree, as if it doesn't exist.

Example .treeignore content:

# --- Shallow Ignore ---
node_modules/
dist/
build/
.vscode/

# --- Complete Ignore ---
.git
.idea
.DS_Store

4. The Target Markdown File: README.md

This is the Markdown file that will be ultimately updated. If your file does not contain these tags, they will be added once. You will need to run the script again to add the directory tree:

<!-- TREE_START -->
<!-- Your directory tree will appear between these tags -->
<!-- TREE_END -->

5. The Descriptions File: tree-descriptions.yml

You can add descriptions for files or directories in your project here. Of course, you can also choose not to add any descriptions.

# Add descriptions for files or directories here, using the format "'path/': 'Your description'".
# Example:
'scripts/md-tree-updater/': 'Contains the scripts for the directory tree updater.'
'README.md': 'The main documentation for the project.'