markdown-magic-transform-treefile-extended

This markdown-magic transform generates a dynamic file tree in your markdown files. It's an extended version of the built-in fileTree transform, with additional options for customizing the output.

Table of Contents

• Installation
• Usage
  • Examples
    • Basic Usage
    • Show File Sizes Use the showSize option to display the size of each
    • Show Descriptions
    • Show File Sizes and Descriptions
    • Show Descriptions from File
    • Custom Root
    • Maximum Depth
    • Only Directories
    • Only Files
    • Flat Tree
    • Exclude Files
    • Pattern Matching
• Options
• Contributing
• License
• Acknowledgments
• Project Structure

Installation

Install the package using npm:

npm install --save-dev markdown-magic-transform-treefile-extended

Usage

1. Add an HTML comment to your README.md:

   This comment will be replaced by the file tree.

   <!-- __doc-gen__ fileTreeExtended -->
   <!-- __end-doc-gen__ -->

2. Create and configure the transform in markdown-magic.config.js:

   const fileTreeExtended = require('markdown-magic-transform-treefile-extended');
   
   module.exports = {
     transforms: {
       fileTreeExtended,
     },
   };

3. Run the markdown-magic command:

   npx markdown-magic README.md --config markdown-magic.config.js

4. README.md should now look like this:

   <!-- __doc-gen__ fileTreeExtended -->

   markdown-magic-transform-treefile-extended/
   ├── .qodo
   │   ├── agents
   │   └── workflows
   ├── .gitignore
   ├── .prettierrc.json
   ├── CHANGELOG.md
   ├── CONTRIBUTING.md
   ├── eslint.config.mjs
   ├── index.js
   ├── LICENSE
   ├── markdown-magic.config.js
   ├── package-lock.json
   ├── package.json
   ├── README.md
   └── RULES_OF_CONDUCT.md

   <!-- __end-doc-gen__ -->

Examples

Basic Usage

This is the default output of the transform.

<!-- __doc-gen__ fileTreeExtended -->

markdown-magic-transform-treefile-extended/
├── .qodo
│   ├── agents
│   └── workflows
├── .gitignore
├── .prettierrc.json
├── CHANGELOG.md
├── CONTRIBUTING.md
├── eslint.config.mjs
├── index.js
├── LICENSE
├── markdown-magic.config.js
├── package-lock.json
├── package.json
├── README.md
└── RULES_OF_CONDUCT.md

<!-- __end-doc-gen__ -->

Show File Sizes Use the showSize option to display the size of each

file.

<!-- __doc-gen__ fileTreeExtended showSize=true -->

markdown-magic-transform-treefile-extended/
├── .qodo
│   ├── agents
│   └── workflows
├── .gitignore (2.1 KB)
├── .prettierrc.json (68 B)
├── CHANGELOG.md (3.9 KB)
├── CONTRIBUTING.md (1.1 KB)
├── eslint.config.mjs (1.1 KB)
├── index.js (8.1 KB)
├── LICENSE (1.1 KB)
├── markdown-magic.config.js (1.9 KB)
├── package-lock.json (339.1 KB)
├── package.json (2.9 KB)
├── README.md (26.8 KB)
└── RULES_OF_CONDUCT.md (829 B)

<!-- __end-doc-gen__ -->

Show Descriptions

Use the showDescriptions option to display the descriptions of files and folders. The descriptions are sourced from the descriptions property in transformDefaults.fileTreeExtended in your markdown-magic.config.js file.

module.exports = {
  transformDefaults: {
    BADGES: {
      style: 'for-the-badge',
    },
    fileTreeExtended: {
      exclude: ['node_modules', '.git', '.vscode', '.DS_Store'],
      descriptions: {
        '.qodo':
          'Qodana is a static analysis tool that can be used to find bugs and improve code quality.',
        node_modules: "This directory contains all the project's dependencies.",
        '.gitignore':
          'This file specifies which files and folders should be ignored by Git.',
        'CONTRIBUTING.md':
          'This file provides guidelines for contributing to the project.',
        'index.js':
          'This is the main entry point of the `fileTreeExtended` transform.',
        LICENSE: "This file contains the project's license information.",
        'markdown-magic.config.js':
          'This is the configuration file for `markdown-magic`.',
        'package-lock.json':
          'This file is automatically generated for any operations where `npm` modifies either the `node_modules` tree, or `package.json`.',
        'package.json':
          'This file contains metadata about the project and its dependencies.',
        'README.md': 'This file provides a general overview of the project.',
        '_descriptions.json':
          'This JSON file contains descriptions for files to be used in the dynamic file tree.',
        'eslint.config.mjs':
          'This is the configuration file for ESLint, a tool for identifying and reporting on patterns found in ECMAScript/JavaScript code.',
        'RULES_OF_CONDUCT.md':
          "This file outlines the rules of conduct for the project's community.",
      },
    },
  },
  transforms: {
    SCRIPTS: require('markdown-magic-scripts'),
    BADGES: require('markdown-magic-transform-badges'),
    ACKNOWLEDGEMENTS: require('markdown-magic-transform-acknowledgements'),
    fileTreeExtended: require('./index'),
  },
};

<!-- __doc-gen__ fileTreeExtended showSize=true -->

markdown-magic-transform-treefile-extended/
├── .qodo                       # Qodana is a static analysis tool that can be used to find bugs and improve code quality.
│   ├── agents
│   └── workflows
├── .gitignore                  # This file specifies which files and folders should be ignored by Git.
├── .prettierrc.json
├── CHANGELOG.md
├── CONTRIBUTING.md             # This file provides guidelines for contributing to the project.
├── eslint.config.mjs           # This is the configuration file for ESLint, a tool for identifying and reporting on patterns found in ECMAScript/JavaScript code.
├── index.js                    # This is the main entry point of the `fileTreeExtended` transform.
├── LICENSE                     # This file contains the project's license information.
├── markdown-magic.config.js    # This is the configuration file for `markdown-magic`.
├── package-lock.json           # This file is automatically generated for any operations where `npm` modifies either the `node_modules` tree, or `package.json`.
├── package.json                # This file contains metadata about the project and its dependencies.
├── README.md                   # This file provides a general overview of the project.
└── RULES_OF_CONDUCT.md         # This file outlines the rules of conduct for the project's community.

<!-- __end-doc-gen__ -->

Show File Sizes and Descriptions

Use both showSize and showDescriptions to display both the size and description of each file. The descriptions are sourced from the descriptions property in transformDefaults.fileTreeExtended in your markdown-magic.config.js file.

<!-- __doc-gen__ fileTreeExtended showSize=true showDescriptions=true -->

markdown-magic-transform-treefile-extended/
├── .qodo                                # Qodana is a static analysis tool that can be used to find bugs and improve code quality.
│   ├── agents
│   └── workflows
├── .gitignore (2.1 KB)                  # This file specifies which files and folders should be ignored by Git.
├── .prettierrc.json (68 B)
├── CHANGELOG.md (3.9 KB)
├── CONTRIBUTING.md (1.1 KB)             # This file provides guidelines for contributing to the project.
├── eslint.config.mjs (1.1 KB)           # This is the configuration file for ESLint, a tool for identifying and reporting on patterns found in ECMAScript/JavaScript code.
├── index.js (8.1 KB)                    # This is the main entry point of the `fileTreeExtended` transform.
├── LICENSE (1.1 KB)                     # This file contains the project's license information.
├── markdown-magic.config.js (1.9 KB)    # This is the configuration file for `markdown-magic`.
├── package-lock.json (339.1 KB)         # This file is automatically generated for any operations where `npm` modifies either the `node_modules` tree, or `package.json`.
├── package.json (2.9 KB)                # This file contains metadata about the project and its dependencies.
├── README.md (26.8 KB)                  # This file provides a general overview of the project.
└── RULES_OF_CONDUCT.md (829 B)          # This file outlines the rules of conduct for the project's community.

<!-- __end-doc-gen__ -->

Show Descriptions from File

Use the descriptionsFile option to load descriptions from an external JSON file.

<!-- __doc-gen__ fileTreeExtended showDescriptions=true descriptionsFile="_descriptions.json" -->

markdown-magic-transform-treefile-extended/
├── .qodo                       # Qodana is a static analysis tool that can be used to find bugs and improve code quality.
│   ├── agents
│   └── workflows
├── .gitignore                  # This file specifies which files and folders should be ignored by Git.
├── .prettierrc.json
├── CHANGELOG.md
├── CONTRIBUTING.md             # This file provides guidelines for contributing to the project.
├── eslint.config.mjs           # This is the configuration file for ESLint, a tool for identifying and reporting on patterns found in ECMAScript/JavaScript code.
├── index.js                    # This is the main entry point of the `fileTreeExtended` transform.
├── LICENSE                     # This file contains the project's license information.
├── markdown-magic.config.js    # This is the configuration file for `markdown-magic`.
├── package-lock.json           # This file is automatically generated for any operations where `npm` modifies either the `node_modules` tree, or `package.json`.
├── package.json                # This file contains metadata about the project and its dependencies.
├── README.md                   # This file provides a general overview of the project.
└── RULES_OF_CONDUCT.md         # This file outlines the rules of conduct for the project's community.

<!-- __end-doc-gen__ -->

Custom Root

Label Use the root option to set a custom label for the root of the file tree.

<!-- __doc-gen__ fileTreeExtended root="My Project" -->

My Project
├── .qodo
│   ├── agents
│   └── workflows
├── .gitignore
├── .prettierrc.json
├── CHANGELOG.md
├── CONTRIBUTING.md
├── eslint.config.mjs
├── index.js
├── LICENSE
├── markdown-magic.config.js
├── package-lock.json
├── package.json
├── README.md
└── RULES_OF_CONDUCT.md

<!-- __end-doc-gen__ -->

Maximum Depth

Use the maxDepth option to limit the depth of the file tree.

<!-- __doc-gen__ fileTreeExtended maxDepth=1 -->

markdown-magic-transform-treefile-extended/
├── .qodo
├── .gitignore
├── .prettierrc.json
├── CHANGELOG.md
├── CONTRIBUTING.md
├── eslint.config.mjs
├── index.js
├── LICENSE
├── markdown-magic.config.js
├── package-lock.json
├── package.json
├── README.md
└── RULES_OF_CONDUCT.md

<!-- __end-doc-gen__ -->

Only Directories

Use the dirsOnly option to show only directories in the file tree.

<!-- __doc-gen__ fileTreeExtended dirsOnly=true -->

markdown-magic-transform-treefile-extended/
├── .qodo
│   ├── agents
│   └── workflows
├── .gitignore
├── .prettierrc.json
├── CHANGELOG.md
├── CONTRIBUTING.md
├── eslint.config.mjs
├── index.js
├── LICENSE
├── markdown-magic.config.js
├── package-lock.json
├── package.json
├── README.md
└── RULES_OF_CONDUCT.md

<!-- __end-doc-gen__ -->

Only Files

Use the filesOnly option to show only files in the file tree.

<!-- __doc-gen__ fileTreeExtended filesOnly=true -->

markdown-magic-transform-treefile-extended/
├── .qodo
│   ├── agents
│   └── workflows
├── .gitignore
├── .prettierrc.json
├── CHANGELOG.md
├── CONTRIBUTING.md
├── eslint.config.mjs
├── index.js
├── LICENSE
├── markdown-magic.config.js
├── package-lock.json
├── package.json
├── README.md
└── RULES_OF_CONDUCT.md

<!-- __end-doc-gen__ -->

Flat Tree

Use the flat option to render a flat list instead of a tree.

<!-- __doc-gen__ fileTreeExtended flat=true -->

.gitignore
.prettierrc.json
.qodo
CHANGELOG.md
CONTRIBUTING.md
eslint.config.mjs
index.js
LICENSE
markdown-magic.config.js
package-lock.json
package.json
README.md
RULES_OF_CONDUCT.md
.qodo/agents
.qodo/workflows

<!-- __end-doc-gen__ -->

Exclude Files

Use the exclude option to exclude files or directories from the output.

<!-- __doc-gen__ fileTreeExtended exclude="['package.json', 'package-lock.json']" -->

markdown-magic-transform-treefile-extended/
├── .qodo
│   ├── agents
│   └── workflows
├── .gitignore
├── .prettierrc.json
├── CHANGELOG.md
├── CONTRIBUTING.md
├── eslint.config.mjs
├── index.js
├── LICENSE
├── markdown-magic.config.js
├── README.md
└── RULES_OF_CONDUCT.md

<!-- __end-doc-gen__ -->

Pattern Matching

Use the pattern option to include only files and directories that match a glob pattern.

<!-- __doc-gen__ fileTreeExtended pattern="['**/*.js']" -->

markdown-magic-transform-treefile-extended/

<!-- __end-doc-gen__ -->

Options

Options can be provided in two ways:

1. In the HTML comment: Options can be added as key=value or "key"="value" pairs

2. In markdown-magic.config.js: You can provide default values for the transform in the transformDefaults section of your markdown-magic.config.js file. These defaults will be used unless overridden in the HTML comment.

| Option | Type | Default | Description | | ------------------ | ----------------------- | --------------------- | --------------------------------------------------------- | | descriptions | object or function | {} | Map or function to provide descriptions for files/folders | | descriptionsFile | string or null | null | Path to external JSON file with descriptions | | dirsOnly | boolean | false | Include only directories in the output | | exclude | string[] | [] | List of paths to exclude from output | | filesOnly | boolean | false | Include only files in the output | | flat | boolean | false | Render a flat list instead of a tree | | ignore | string[] | ["node_modules"] | Glob patterns to ignore | | maxDepth | number or undefined | undefined | Maximum folder depth to scan | | pattern | string[] | ["**/*"] | Glob pattern(s) to include | | root | string or undefined | basename(dir) + "/" | Custom label for the root node | | showDescriptions | boolean | false | Whether to show descriptions next to entries | | showHidden | boolean | true | Whether to show hidden files and folders (those starting with a dot). Set to false to exclude them | | showSize | boolean | false | Whether to show file sizes in parentheses. | | dir | string | process.cwd() | Root directory to scan |

Contributing

See CONTRIBUTING.md for details on how to raise issues, propose changes, and submit pull requests. In short: - Open issues for bugs or feature requests with clear reproduction steps.

• For code contributions, fork the repo, create a branch, add tests, and open a PR against main. ## Helper Scripts

• docs — Generate documentation by processing README.md with markdown-magic. (line 13)

  npx markdown-magic **/*.md --config ./markdown-magic.config.js

• fix — Automatically fix linting issues and format codebase. (line 8)

  npm run lint:fix && npm run format && npm run format:package

• format — Format all project files using Prettier. (line 9)

  prettier --write .

• format:package — Format the package.json file using Prettier. (line 10)

  prettier --write package.json

• lint — Lint all project files to ensure code quality and consistency. (line 11)

  eslint . --ext .js,.json,.yaml,.yml,.md

• lint:fix — Lint all project files and automatically fix issues where possible. (line 12)

  eslint . --ext .js,.json,.yaml,.yml,.md --fix

• prep — Prepare the project for publishing by generating docs and formatting code. (line 14)

  npm run docs && npm run fix

• test — Run the test suite using Jest. (line 7)

  jest --passWithNoTests

License

This project is licensed under the terms of the MIT License. See the LICENSE file for details.

Acknowledgments

• eslint — An AST-based pattern checker for JavaScript.
• eslint-config-prettier — No description available
• eslint-plugin-prettier — No description available
• fast-glob — It's a very fast and efficient glob library for Node.js
• jest — Delightful JavaScript Testing.
• prettier — Prettier is an opinionated code formatter

Project Structure

Root
├── .qodo                       # Qodana is a static analysis tool that can be used to find bugs and improve code quality.
│   ├── agents
│   └── workflows
├── .gitignore                  # This file specifies which files and folders should be ignored by Git.
├── .prettierrc.json
├── CHANGELOG.md
├── CONTRIBUTING.md             # This file provides guidelines for contributing to the project.
├── eslint.config.mjs           # This is the configuration file for ESLint, a tool for identifying and reporting on patterns found in ECMAScript/JavaScript code.
├── index.js                    # This is the main entry point of the `fileTreeExtended` transform.
├── LICENSE                     # This file contains the project's license information.
├── markdown-magic.config.js    # This is the configuration file for `markdown-magic`.
├── package-lock.json           # This file is automatically generated for any operations where `npm` modifies either the `node_modules` tree, or `package.json`.
├── package.json                # This file contains metadata about the project and its dependencies.
├── README.md                   # This file provides a general overview of the project.
└── RULES_OF_CONDUCT.md         # This file outlines the rules of conduct for the project's community.