| Name | xl2md JSON |
| Version |
1.1
JSON |
| download |
| home_page | None |
| Summary | A fast and configurable CLI tool and library for converting Excel sheets into clean Markdown tables. |
| upload_time | 2025-08-30 21:25:26 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | MIT License |
| keywords |
excel
markdown
converter
pandas
automation
cli
xlsx
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# xl2md
A simple, fast, and configurable utility to convert sheets in an Excel workbook into clean Markdown tables.
Manually copying data from Excel into Markdown is tedious and error-prone. **`xl2md`** automates this process, preserving the structure of your sheets and providing a command-line tool for quick conversions and a Python library for advanced control.
## Key Features
* **Batch Conversion**: Automatically converts every sheet in a workbook to a separate Markdown file.
* **Simple CLI**: A straightforward command-line interface for easy use in any terminal.
* **Flexible Library**: Import the converter into your own Python scripts for customized workflows.
* **Smart Formatting**: Handles common Excel quirks like `Unnamed:` columns and correctly escapes special Markdown characters.
* **Safe Filenames**: Automatically creates "slugified," web-safe filenames from sheet names (e.g., "Q3 Financial Report" becomes `Q3-Financial-Report.md`).
* **Customizable**: Control the output directory, overwrite behavior, and more.
-----
## Installation
You can install `xl2md` directly from PyPI using pip.
```bash
pip install xl2md
```
-----
## Usage
`xl2md` can be used as a command-line tool or as a Python library.
### 1\. Command-Line Interface (CLI)
This is the quickest way to convert a file. The basic command requires only the path to your Excel workbook.
**Basic Conversion**
```bash
xl2md path/to/your/workbook.xlsx
```
By default, this command will:
1. Read the `workbook.xlsx` file.
2. Create a new directory named `markdown_sheets` in your current location.
3. Save each converted sheet as a separate `.md` file inside `markdown_sheets`.
**CLI Options**
You can customize the behavior with the following options:
* `--out-dir <directory>`: Specifies a different output directory for the Markdown files.
```bash
xl2md my_data.xlsx --out-dir "converted_docs"
```
* `--overwrite`: Overwrites existing Markdown files in the output directory if they have the same name. Without this flag, existing files will be skipped.
```bash
xl2md my_data.xlsx --overwrite
```
* `--no-safe-filenames`: Uses the original sheet names for filenames instead of converting them to a safe, URL-friendly format. **Warning:** This may cause issues if sheet names contain special characters.
```bash
xl2md "My Workbook.xlsx" --no-safe-filenames
```
* `-v` or `--verbose`: Enables detailed (DEBUG level) logging, which is helpful for troubleshooting.
```bash
xl2md my_data.xlsx -v
```
**Example Combining Options**
```bash
xl2md "Financial Report Q3 2025.xlsx" --out-dir "reports/markdown" --overwrite --verbose
```
-----
### 2\. As a Python Library
For more advanced control, import `ExcelToMarkdownConverter` and `ConverterOptions` into your own Python scripts. This allows you to filter sheets, include the DataFrame index, and integrate the conversion into a larger automation workflow.
**Basic Library Usage**
```python
from xl2md import ExcelToMarkdownConverter
# Initialize with the path to your Excel file
converter = ExcelToMarkdownConverter(excel_path="path/to/my_workbook.xlsx")
# Run the conversion with default options
written_files = converter.convert()
print(f"Successfully converted files: {written_files}")
```
**Advanced Configuration**
The `ConverterOptions` class lets you fine-tune the conversion process.
```python
from xl2md import ExcelToMarkdownConverter, ConverterOptions
import logging
# 1. Configure your desired options
options = ConverterOptions(
out_dir="./custom_output", # Set a custom output directory
overwrite=True, # Overwrite existing files
include_index=True, # Include the DataFrame index in the table
index_label="Row ID", # Set a custom label for the index column
log_level=logging.DEBUG, # Set the logging level
# Only convert sheets whose names start with "Report_" (uses regex)
sheet_name_allowlist=[r"Report_.+"],
# Skip any sheets containing the word "Internal" (case-insensitive)
sheet_name_blocklist=[r"Internal"]
)
# 2. Initialize the converter with the file path and custom options
try:
converter = ExcelToMarkdownConverter(
excel_path="financials.xlsx",
options=options
)
# 3. Run the conversion
written_files = converter.convert()
if written_files:
print(f"✅ Conversion complete. Files written to '{options.out_dir}':")
for f in written_files:
print(f" - {f}")
else:
print("⚠️ No sheets were converted. Check your allow/block lists and file content.")
except Exception as e:
print(f"❌ An error occurred: {e}")
```
-----
## Contributing
Contributions are welcome\! If you have a suggestion or find a bug, please open an issue on the GitHub repository. Pull requests are also greatly appreciated.
1. Fork the repository.
2. Create your feature branch (`git checkout -b feature/AmazingFeature`).
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`).
4. Push to the branch (`git push origin feature/AmazingFeature`).
5. Open a Pull Request.
-----
## License
This project is licensed under the MIT License. See the `LICENSE` file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "xl2md",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Nagur Shareef Shaik <nagurshareef.shaik@ust.com>",
"keywords": "excel, markdown, converter, pandas, automation, cli, xlsx",
"author": null,
"author_email": "\"UST Global Inc.\" <nagurshareef.shaik@ust.com>",
"download_url": "https://files.pythonhosted.org/packages/c3/0f/5a8a1d60040d1bf48564ae8d85f350c4d59640e95bc93dc70442d11b1020/xl2md-1.1.tar.gz",
"platform": null,
"description": "# xl2md\n\nA simple, fast, and configurable utility to convert sheets in an Excel workbook into clean Markdown tables.\n\nManually copying data from Excel into Markdown is tedious and error-prone. **`xl2md`** automates this process, preserving the structure of your sheets and providing a command-line tool for quick conversions and a Python library for advanced control.\n\n## Key Features\n\n * **Batch Conversion**: Automatically converts every sheet in a workbook to a separate Markdown file.\n * **Simple CLI**: A straightforward command-line interface for easy use in any terminal.\n * **Flexible Library**: Import the converter into your own Python scripts for customized workflows.\n * **Smart Formatting**: Handles common Excel quirks like `Unnamed:` columns and correctly escapes special Markdown characters.\n * **Safe Filenames**: Automatically creates \"slugified,\" web-safe filenames from sheet names (e.g., \"Q3 Financial Report\" becomes `Q3-Financial-Report.md`).\n * **Customizable**: Control the output directory, overwrite behavior, and more.\n\n-----\n\n## Installation\n\nYou can install `xl2md` directly from PyPI using pip.\n\n```bash\npip install xl2md\n```\n\n-----\n\n## Usage\n\n`xl2md` can be used as a command-line tool or as a Python library.\n\n### 1\\. Command-Line Interface (CLI)\n\nThis is the quickest way to convert a file. The basic command requires only the path to your Excel workbook.\n\n**Basic Conversion**\n\n```bash\nxl2md path/to/your/workbook.xlsx\n```\n\nBy default, this command will:\n\n1. Read the `workbook.xlsx` file.\n2. Create a new directory named `markdown_sheets` in your current location.\n3. Save each converted sheet as a separate `.md` file inside `markdown_sheets`.\n\n**CLI Options**\n\nYou can customize the behavior with the following options:\n\n * `--out-dir <directory>`: Specifies a different output directory for the Markdown files.\n\n ```bash\n xl2md my_data.xlsx --out-dir \"converted_docs\"\n ```\n\n * `--overwrite`: Overwrites existing Markdown files in the output directory if they have the same name. Without this flag, existing files will be skipped.\n\n ```bash\n xl2md my_data.xlsx --overwrite\n ```\n\n * `--no-safe-filenames`: Uses the original sheet names for filenames instead of converting them to a safe, URL-friendly format. **Warning:** This may cause issues if sheet names contain special characters.\n\n ```bash\n xl2md \"My Workbook.xlsx\" --no-safe-filenames\n ```\n\n * `-v` or `--verbose`: Enables detailed (DEBUG level) logging, which is helpful for troubleshooting.\n\n ```bash\n xl2md my_data.xlsx -v\n ```\n\n**Example Combining Options**\n\n```bash\nxl2md \"Financial Report Q3 2025.xlsx\" --out-dir \"reports/markdown\" --overwrite --verbose\n```\n\n-----\n\n### 2\\. As a Python Library\n\nFor more advanced control, import `ExcelToMarkdownConverter` and `ConverterOptions` into your own Python scripts. This allows you to filter sheets, include the DataFrame index, and integrate the conversion into a larger automation workflow.\n\n**Basic Library Usage**\n\n```python\nfrom xl2md import ExcelToMarkdownConverter\n\n# Initialize with the path to your Excel file\nconverter = ExcelToMarkdownConverter(excel_path=\"path/to/my_workbook.xlsx\")\n\n# Run the conversion with default options\nwritten_files = converter.convert()\n\nprint(f\"Successfully converted files: {written_files}\")\n```\n\n**Advanced Configuration**\n\nThe `ConverterOptions` class lets you fine-tune the conversion process.\n\n```python\nfrom xl2md import ExcelToMarkdownConverter, ConverterOptions\nimport logging\n\n# 1. Configure your desired options\noptions = ConverterOptions(\n out_dir=\"./custom_output\", # Set a custom output directory\n overwrite=True, # Overwrite existing files\n include_index=True, # Include the DataFrame index in the table\n index_label=\"Row ID\", # Set a custom label for the index column\n log_level=logging.DEBUG, # Set the logging level\n \n # Only convert sheets whose names start with \"Report_\" (uses regex)\n sheet_name_allowlist=[r\"Report_.+\"],\n \n # Skip any sheets containing the word \"Internal\" (case-insensitive)\n sheet_name_blocklist=[r\"Internal\"]\n)\n\n# 2. Initialize the converter with the file path and custom options\ntry:\n converter = ExcelToMarkdownConverter(\n excel_path=\"financials.xlsx\",\n options=options\n )\n\n # 3. Run the conversion\n written_files = converter.convert()\n\n if written_files:\n print(f\"\u2705 Conversion complete. Files written to '{options.out_dir}':\")\n for f in written_files:\n print(f\" - {f}\")\n else:\n print(\"\u26a0\ufe0f No sheets were converted. Check your allow/block lists and file content.\")\n\nexcept Exception as e:\n print(f\"\u274c An error occurred: {e}\")\n\n```\n\n-----\n\n## Contributing\n\nContributions are welcome\\! If you have a suggestion or find a bug, please open an issue on the GitHub repository. Pull requests are also greatly appreciated.\n\n1. Fork the repository.\n2. Create your feature branch (`git checkout -b feature/AmazingFeature`).\n3. Commit your changes (`git commit -m 'Add some AmazingFeature'`).\n4. Push to the branch (`git push origin feature/AmazingFeature`).\n5. Open a Pull Request.\n\n-----\n\n## License\n\nThis project is licensed under the MIT License. See the `LICENSE` file for details.\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "A fast and configurable CLI tool and library for converting Excel sheets into clean Markdown tables.",
"version": "1.1",
"project_urls": {
"Bug Tracker": "https://github.com/UST-Global-GenAI/xl2md/issues",
"Documentation": "https://github.com/UST-Global-GenAI/xl2md/blob/main/README.md",
"Homepage": "https://github.com/UST-Global-GenAI/xl2md",
"Organization": "https://www.ust.com/"
},
"split_keywords": [
"excel",
" markdown",
" converter",
" pandas",
" automation",
" cli",
" xlsx"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "93f5d6f28f6355970167e4a098ed1991fc4279f4dda40e088f38040ff2dce611",
"md5": "5fed5ba451f9db40b83387e1a36c06fd",
"sha256": "a2269e33f6f88517e7052a164b039f2d94a8d630e5bf4d3cac44c9eaa9e4b80c"
},
"downloads": -1,
"filename": "xl2md-1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5fed5ba451f9db40b83387e1a36c06fd",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 9144,
"upload_time": "2025-08-30T21:25:25",
"upload_time_iso_8601": "2025-08-30T21:25:25.157657Z",
"url": "https://files.pythonhosted.org/packages/93/f5/d6f28f6355970167e4a098ed1991fc4279f4dda40e088f38040ff2dce611/xl2md-1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c30f5a8a1d60040d1bf48564ae8d85f350c4d59640e95bc93dc70442d11b1020",
"md5": "94a8bcdad53d957aa4ae71e8242e63f0",
"sha256": "44da5e6eaa82a127f5e16b1bb34f1f104d94a5fa115318b9e4387efbb59988f8"
},
"downloads": -1,
"filename": "xl2md-1.1.tar.gz",
"has_sig": false,
"md5_digest": "94a8bcdad53d957aa4ae71e8242e63f0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 10629,
"upload_time": "2025-08-30T21:25:26",
"upload_time_iso_8601": "2025-08-30T21:25:26.218434Z",
"url": "https://files.pythonhosted.org/packages/c3/0f/5a8a1d60040d1bf48564ae8d85f350c4d59640e95bc93dc70442d11b1020/xl2md-1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-30 21:25:26",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "UST-Global-GenAI",
"github_project": "xl2md",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "xl2md"
}
