| Name | mdfile JSON |
| Version |
0.9.0
JSON |
| download |
| home_page | None |
| Summary | Process and update Markdown files with embedded file/process/var data. |
| upload_time | 2025-08-19 04:12:46 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | <3.15,>=3.10 |
| license | None |
| keywords |
markdown
cli
markdown-processing
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# `MDFile` Overview
A utility that dynamically imports content from external files or commands into your Markdown documents.
Perfect for keeping code samples, data, and command outputs in sync with your documentation.
MDFile supports directly copying data into Markdown files using the following format:
```markdown
# My Project - {{$version}}
Check out this function:
{{file example.py}}
Files used in this project:
{{process ls -a}}
```
After running `mdfile`, you would have where each of the {{}} macros are expanded into the file.
````markdown
# My Project - 0.1.0
Check out this function:
```python
def hello():
print("example")
```
Files used in this project:
```text
mdfile.py __init__.py
````
`mdfile` is able to convert CSV files to Markdown tables as well as pretty print JSON files. Most
file inclusions will autodetect the format based on the file extension to enable browsers to
syntax highlight as needed.
## Key Features
- **Multiple Import Methods**: Import files directly or capture command outputs
- **Smart Formatting**: Automatically applies correct syntax highlighting based on file extension
- **Table Formatting**: Converts CSV data into well-formatted Markdown tables
- **JSON Prettification**: Properly formats and highlights JSON data
- **Direct Markdown Insertion**: Markdown files are imported directly.
- **Variable Expansion**: Commonly used variables are available (e.g., $version)
## Quick Example
The following example shows how to use `mdfile` using the markdown comment tags. These tags allow you
to dynamically update a Markdown file in place since the tags remain after update AND the text between tags
is ignored when the file is updated again. This feature is useful, but can be dangerous if you delete
half of a tag pair.
**Source file (example.py):**
```python
def hello_world():
return "Hello, world!"
```
**In your README.md:**
```markdown
# My Project
Check out this function:
<!--file example.py-->
<!--file end-->
```
**After running `mdfile`:**
````markdown
# My Project
Check out this function:
<!--file example.py-->
```python
def hello_world():
return "Hello, world!"
```
<!--file end-->
````
To make markdown with the output from the `cat factorial.py` shell command. This can be difficult
to get just right depending on the tool you are trying to use to pipe data from because different
command line utilities behave differently when data is displayed in a tty vs. a pipe. In the example
below the `cat` command is used to copy the data into the Markdown file, but any command can be used.
Keep in mind that some tools act differently when they are generating data for a tty compared to
when they are piping data into a file.
`<!--process cat factorial.py-->`
```text
def factorial(n:int):
"""Return factorial of n"""
if n == 0:
return 1
else:
return n * factorial(n - 1)
```
`<!--process end-->`
## Overview
`MDFile` 'converts' different file types to properly formatted Markdown, supporting:
- Code files (.py, .java, .js, and many more)
- Multiple files can be displayed using file globs such as `<!--file *.py-->`.
- CSV files (with table formatting)
- JSON files (pretty printed,with syntax highlighting)
- Markdown files inserted inline.
- Text files (plain text conversion)
- Basic variable substitution.
- Supports Overwrite (<!-- file x.x->) syntax and insertion {{file}} syntax.
**USEFUL NOTE: Paths are relative to the file that you are processing, so if files are in other folders please
reference them to the Markdown file that you are reading from.**
## Installation
If you are interested in development you can just go to GitHub and clone the repository.
``` bash
# Clone the repository
git clone https://github.com/hucker/mdfile.git
cd mdfile
# Install the package
pip install -e .
```
**RECOMMENDED INSTALLATION**
If you are just interested in using `mdfile` as a tool the very best way to do it
is to just install `uv` and run:
```shell
(.venv) chuck@Chucks-Mac-mini mdfile % uv tool install mdfile
Resolved 9 packages in 20ms
Installed 9 packages in 10ms
+ click==8.2.1
+ markdown-it-py==4.0.0
+ mdfile==0.5.0
+ mdurl==0.1.2
+ pygments==2.19.2
+ rich==14.1.0
+ shellingham==1.5.4
+ typer==0.16.0
+ typing-extensions==4.14.1
Installed 1 executable: mdfile
```
And then test it:
```shell
(.venv) chuck@Chucks-Mac-mini mdfile % uvx mdfile --help
Usage: mdfile [OPTIONS] [FILE_NAME]
Convert a file to Markdown based on its extension.
Arguments:
[FILE_NAME] The file to convert to Markdown \[default: README.md]
Options:
-o, --output TEXT Output file (if not specified, prints to
stdout)
-b, --bold TEXT Comma-separated values to make bold (for CSV
files)
--auto-break / --no-auto-break Disable automatic line breaks in CSV headers
\[default: auto-break]
--plain Output plain markdown without rich
formatting
--version -v Show version and exit
--help Show this message and exit.
```
and you should be off and running using this as a tool to update Markdown files anywhere.
## Basic Usage
The basic command for converting files is:
``` bash
uvx mdfile [FILE_PATH] [OPTIONS]
```
If you don't specify a file, it defaults to `README.md`.
### Command Line Options
``` bash
# Convert a file and print to stdout
uvx mdfile README.md
# Disable automatic line breaks in CSV headers
uvx mdfile README.md --no-auto-break
```
## Examples
### CSV to Markdown Table Conversion
#### Original CSV File: `sales_data.csv`
```
Region,Q1 Sales,Q2 Sales,Q3 Sales,Q4 Sales,Total
North,125000,133000,158000,175000,591000
South,105000,130000,115000,163000,513000
East,143000,123000,132000,145000,543000
West,117000,142000,138000,162000,559000
Total,490000,528000,543000,645000,2206000
```
#### Markdown Document with Inclusion: `report.md`
``` markdown
# Quarterly Sales Report
## Regional Sales Data
Here's a breakdown of our quarterly sales by region:
<!--file sales_data.csv-->
<!--file end-->
As we can see from the data, Q4 had the strongest performance across all regions.
```
#### After Running `MDFile`:
``` bash
uvx mdfile report.md --bold "Total" -o final_report.md
```
---
#### Resulting Markdown: `final_report.md`
# Quarterly Sales Report
## Regional Sales Data
Here's a breakdown of our quarterly sales by region:
| Region | Q1 Sales | Q2 Sales | Q3 Sales | Q4 Sales | Total |
|-----------|------------|------------|------------|------------|-------------|
| North | 125000 | 133000 | 158000 | 175000 | 591000 |
| South | 105000 | 130000 | 115000 | 163000 | 513000 |
| East | 143000 | 123000 | 132000 | 145000 | 543000 |
| West | 117000 | 142000 | 138000 | 162000 | 559000 |
| **Total** | **490000** | **528000** | **543000** | **645000** | **2206000** |
As we can see from the data, Q4 had the strongest performance across all regions.
---
### Including JSON Configuration
```json
{"name":"John Doe","age":30,"isStudent":false,"grades":[78,85,90],"address":{"street":"123 Main St","city":"New York","zip":"10001"}}
```
``` markdown
## Configuration
The default configuration is:
<!--file path/to/config.json-->
<!--file end-->
```
The updated `README.md` file is shown below with the JSON pretty printed.
```` markdown
## Configuration
The default configuration is:
<!--file path/to/config.json-->
```json
{
"name": "John Doe",
"age": 30,
"isStudent": false,
"grades": [
78,
85,
90
],
"address": {
"street": "123 Main St",
"city": "New York",
"zip": "10001"
}
}
```
<!--file end-->
````
## File Type Support
`MDFile` supports numerous file extensions allowing MarkDown to correctly syntax highlight:
- Python: `.py`, `.pyw`, `.pyx`, `.pyi`
- JavaScript: `.js`, `.mjs`, `.cjs`
- TypeScript: `.ts`, `.tsx`
- Java: `.java`
- C/C++: `.c`, `.h`, `.cpp`, `.cc`, `.hpp`
- Web: `.html`, `.htm`, `.css`, `.scss`
- Data: `.json`, `.yaml`, `.yml`, `.csv`
- Configuration: `.ini`, `.cfg`, `.conf`
- Shell: `.sh`, `.bash`, `.zsh`
- And many more!
These file extensions map use the standard triple back tick text blocks available in Markdown.
## Options for CSV Files
When converting CSV files, you have additional options:
- `--bold VALUE1,VALUE2,...` - Make specific columns bold in the table
- `--auto-break/--no-auto-break` - Control automatic line breaks in CSV headers
## Variable Substitution
`mdfile` supports a basic form of variable substitution. At this time the following are supported:
| Variable | Description |
|--------------|----------------------|
| `{{$name}}` | `mdfile` |
| `{{$date}}` | current date |
| `{{$time}}` | current time |
| `{{$version}}` | build version |
These values are imported directly into the markdown file with no special Markdown tags, just raw text
this allows you to have text such as
```App **{{$name}}** version **{{$version}}** was created on {{$date}}```
To get the text
App **mdfile** version **0.10.0** was created on 1/1/2024
### UVX
If you installed `mdfile` as a `uv` tool then you can run `mdfile` from anywhere using
the `uvx` tool.
```bash
uvx mdfile ../README_template.md --output ../README.md
```
``` bash
uvx mdfile documentation.md -o updated_docs.md
```
## Disclaimer
This tool was made open source because it is somewhat useful as it grew features over time. It is
not a great example of how to write clean code since it grew organically in several projects. Don't
be too harsh judging the code.
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## License
[MIT License](LICENSE)
Raw data
{
"_id": null,
"home_page": null,
"name": "mdfile",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.15,>=3.10",
"maintainer_email": null,
"keywords": "markdown, CLI, markdown-processing",
"author": null,
"author_email": "Chuck Bass <chuck@acrocad.net>",
"download_url": "https://files.pythonhosted.org/packages/ec/95/ee268b114170b2c1357badb45ca0289d9b1b0d99258e66e6283993764102/mdfile-0.9.0.tar.gz",
"platform": null,
"description": "\n# `MDFile` Overview\nA utility that dynamically imports content from external files or commands into your Markdown documents. \nPerfect for keeping code samples, data, and command outputs in sync with your documentation.\n\nMDFile supports directly copying data into Markdown files using the following format:\n\n```markdown\n# My Project - {{$version}}\n\nCheck out this function:\n\n{{file example.py}}\n\nFiles used in this project:\n{{process ls -a}}\n\n \n```\n\nAfter running `mdfile`, you would have where each of the {{}} macros are expanded into the file.\n\n````markdown\n# My Project - 0.1.0\n\nCheck out this function:\n\n```python\ndef hello():\n print(\"example\")\n```\n\nFiles used in this project:\n```text\nmdfile.py __init__.py\n````\n\n`mdfile` is able to convert CSV files to Markdown tables as well as pretty print JSON files. Most\nfile inclusions will autodetect the format based on the file extension to enable browsers to \nsyntax highlight as needed.\n\n## Key Features\n\n- **Multiple Import Methods**: Import files directly or capture command outputs\n- **Smart Formatting**: Automatically applies correct syntax highlighting based on file extension\n- **Table Formatting**: Converts CSV data into well-formatted Markdown tables\n- **JSON Prettification**: Properly formats and highlights JSON data\n- **Direct Markdown Insertion**: Markdown files are imported directly.\n- **Variable Expansion**: Commonly used variables are available (e.g., $version)\n\n## Quick Example\n\nThe following example shows how to use `mdfile` using the markdown comment tags. These tags allow you\nto dynamically update a Markdown file in place since the tags remain after update AND the text between tags \nis ignored when the file is updated again. This feature is useful, but can be dangerous if you delete\nhalf of a tag pair.\n\n**Source file (example.py):**\n```python\ndef hello_world():\n return \"Hello, world!\"\n```\n\n**In your README.md:**\n```markdown\n# My Project\n\nCheck out this function:\n\n<!--file example.py-->\n<!--file end-->\n```\n\n**After running `mdfile`:**\n````markdown\n# My Project\n\nCheck out this function:\n\n<!--file example.py-->\n```python\ndef hello_world():\n return \"Hello, world!\"\n ```\n<!--file end-->\n````\n\nTo make markdown with the output from the `cat factorial.py` shell command. This can be difficult\nto get just right depending on the tool you are trying to use to pipe data from because different\ncommand line utilities behave differently when data is displayed in a tty vs. a pipe. In the example\nbelow the `cat` command is used to copy the data into the Markdown file, but any command can be used.\nKeep in mind that some tools act differently when they are generating data for a tty compared to \nwhen they are piping data into a file.\n\n`<!--process cat factorial.py-->`\n```text\ndef factorial(n:int):\n \"\"\"Return factorial of n\"\"\"\n if n == 0:\n return 1\n else:\n return n * factorial(n - 1)\n```\n`<!--process end-->`\n\n## Overview\n`MDFile` 'converts' different file types to properly formatted Markdown, supporting:\n- Code files (.py, .java, .js, and many more)\n- Multiple files can be displayed using file globs such as `<!--file *.py-->`.\n- CSV files (with table formatting)\n- JSON files (pretty printed,with syntax highlighting)\n- Markdown files inserted inline.\n- Text files (plain text conversion)\n- Basic variable substitution.\n- Supports Overwrite (<!-- file x.x->) syntax and insertion {{file}} syntax.\n\n\n**USEFUL NOTE: Paths are relative to the file that you are processing, so if files are in other folders please\nreference them to the Markdown file that you are reading from.**\n\n\n## Installation\n\nIf you are interested in development you can just go to GitHub and clone the repository. \n\n``` bash\n# Clone the repository\ngit clone https://github.com/hucker/mdfile.git\ncd mdfile\n\n# Install the package\npip install -e .\n```\n\n**RECOMMENDED INSTALLATION**\nIf you are just interested in using `mdfile` as a tool the very best way to do it\nis to just install `uv` and run:\n\n```shell\n(.venv) chuck@Chucks-Mac-mini mdfile % uv tool install mdfile \nResolved 9 packages in 20ms\nInstalled 9 packages in 10ms\n + click==8.2.1\n + markdown-it-py==4.0.0\n + mdfile==0.5.0\n + mdurl==0.1.2\n + pygments==2.19.2\n + rich==14.1.0\n + shellingham==1.5.4\n + typer==0.16.0\n + typing-extensions==4.14.1\nInstalled 1 executable: mdfile\n```\n\nAnd then test it:\n\n```shell\n(.venv) chuck@Chucks-Mac-mini mdfile % uvx mdfile --help \n\nUsage: mdfile [OPTIONS] [FILE_NAME]\n\n Convert a file to Markdown based on its extension.\n\nArguments:\n [FILE_NAME] The file to convert to Markdown \\[default: README.md]\n\nOptions:\n -o, --output TEXT Output file (if not specified, prints to\n stdout)\n -b, --bold TEXT Comma-separated values to make bold (for CSV\n files)\n --auto-break / --no-auto-break Disable automatic line breaks in CSV headers\n \\[default: auto-break]\n --plain Output plain markdown without rich\n formatting\n --version -v Show version and exit \n --help Show this message and exit.\n```\n\nand you should be off and running using this as a tool to update Markdown files anywhere.\n\n## Basic Usage\n\n\nThe basic command for converting files is:\n``` bash\nuvx mdfile [FILE_PATH] [OPTIONS]\n```\nIf you don't specify a file, it defaults to `README.md`.\n### Command Line Options\n``` bash\n# Convert a file and print to stdout\nuvx mdfile README.md\n\n# Disable automatic line breaks in CSV headers\nuvx mdfile README.md --no-auto-break\n```\n## Examples\n### CSV to Markdown Table Conversion\n#### Original CSV File: `sales_data.csv`\n``` \nRegion,Q1 Sales,Q2 Sales,Q3 Sales,Q4 Sales,Total\nNorth,125000,133000,158000,175000,591000\nSouth,105000,130000,115000,163000,513000\nEast,143000,123000,132000,145000,543000\nWest,117000,142000,138000,162000,559000\nTotal,490000,528000,543000,645000,2206000\n```\n#### Markdown Document with Inclusion: `report.md`\n``` markdown\n# Quarterly Sales Report\n\n## Regional Sales Data\n\nHere's a breakdown of our quarterly sales by region:\n\n<!--file sales_data.csv-->\n<!--file end-->\n\nAs we can see from the data, Q4 had the strongest performance across all regions.\n```\n#### After Running `MDFile`:\n``` bash\nuvx mdfile report.md --bold \"Total\" -o final_report.md\n```\n\n---\n\n#### Resulting Markdown: `final_report.md`\n\n# Quarterly Sales Report\n\n## Regional Sales Data\n\nHere's a breakdown of our quarterly sales by region:\n\n| Region | Q1 Sales | Q2 Sales | Q3 Sales | Q4 Sales | Total |\n|-----------|------------|------------|------------|------------|-------------|\n| North | 125000 | 133000 | 158000 | 175000 | 591000 |\n| South | 105000 | 130000 | 115000 | 163000 | 513000 |\n| East | 143000 | 123000 | 132000 | 145000 | 543000 |\n| West | 117000 | 142000 | 138000 | 162000 | 559000 |\n| **Total** | **490000** | **528000** | **543000** | **645000** | **2206000** |\n\n\nAs we can see from the data, Q4 had the strongest performance across all regions.\n\n---\n\n### Including JSON Configuration\n\n```json\n{\"name\":\"John Doe\",\"age\":30,\"isStudent\":false,\"grades\":[78,85,90],\"address\":{\"street\":\"123 Main St\",\"city\":\"New York\",\"zip\":\"10001\"}}\n```\n\n``` markdown\n## Configuration\n\nThe default configuration is:\n\n<!--file path/to/config.json-->\n<!--file end-->\n```\n\nThe updated `README.md` file is shown below with the JSON pretty printed.\n\n```` markdown\n## Configuration\n\nThe default configuration is:\n\n<!--file path/to/config.json-->\n```json\n{\n \"name\": \"John Doe\",\n \"age\": 30,\n \"isStudent\": false,\n \"grades\": [\n 78,\n 85,\n 90\n ],\n \"address\": {\n \"street\": \"123 Main St\",\n \"city\": \"New York\",\n \"zip\": \"10001\"\n }\n}\n```\n<!--file end-->\n````\n\n## File Type Support\n`MDFile` supports numerous file extensions allowing MarkDown to correctly syntax highlight:\n- Python: `.py`, `.pyw`, `.pyx`, `.pyi`\n- JavaScript: `.js`, `.mjs`, `.cjs`\n- TypeScript: `.ts`, `.tsx`\n- Java: `.java`\n- C/C++: `.c`, `.h`, `.cpp`, `.cc`, `.hpp`\n- Web: `.html`, `.htm`, `.css`, `.scss`\n- Data: `.json`, `.yaml`, `.yml`, `.csv`\n- Configuration: `.ini`, `.cfg`, `.conf`\n- Shell: `.sh`, `.bash`, `.zsh`\n- And many more!\n\nThese file extensions map use the standard triple back tick text blocks available in Markdown.\n\n## Options for CSV Files\nWhen converting CSV files, you have additional options:\n- `--bold VALUE1,VALUE2,...` - Make specific columns bold in the table\n- `--auto-break/--no-auto-break` - Control automatic line breaks in CSV headers\n\n## Variable Substitution\n`mdfile` supports a basic form of variable substitution. At this time the following are supported:\n\n| Variable | Description |\n|--------------|----------------------|\n| `{{$name}}` | `mdfile` |\n| `{{$date}}` | current date |\n| `{{$time}}` | current time |\n| `{{$version}}` | build version |\n\nThese values are imported directly into the markdown file with no special Markdown tags, just raw text\nthis allows you to have text such as\n\n```App **{{$name}}** version **{{$version}}** was created on {{$date}}```\n\nTo get the text\n\nApp **mdfile** version **0.10.0** was created on 1/1/2024\n\n### UVX\nIf you installed `mdfile` as a `uv` tool then you can run `mdfile` from anywhere using \nthe `uvx` tool.\n\n```bash\nuvx mdfile ../README_template.md --output ../README.md\n```\n\n``` bash\nuvx mdfile documentation.md -o updated_docs.md\n```\n\n## Disclaimer\nThis tool was made open source because it is somewhat useful as it grew features over time. It is\nnot a great example of how to write clean code since it grew organically in several projects. Don't\nbe too harsh judging the code.\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add some amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n\n## License\n[MIT License](LICENSE)\n",
"bugtrack_url": null,
"license": null,
"summary": "Process and update Markdown files with embedded file/process/var data.",
"version": "0.9.0",
"project_urls": {
"Homepage": "https://github.com/hucker/mdfile"
},
"split_keywords": [
"markdown",
" cli",
" markdown-processing"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "6fb8d69a13946b322f28cd6fd409aaf51cda3b3b4b136c9de8717bc826fe0b7f",
"md5": "5792d5e89ca961f470fb71a276749677",
"sha256": "abe713805e8998264d7fbec5611e5ccfcc5fbef734e264989b4c4cdc267964d4"
},
"downloads": -1,
"filename": "mdfile-0.9.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5792d5e89ca961f470fb71a276749677",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.15,>=3.10",
"size": 17298,
"upload_time": "2025-08-19T04:12:45",
"upload_time_iso_8601": "2025-08-19T04:12:45.300789Z",
"url": "https://files.pythonhosted.org/packages/6f/b8/d69a13946b322f28cd6fd409aaf51cda3b3b4b136c9de8717bc826fe0b7f/mdfile-0.9.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "ec95ee268b114170b2c1357badb45ca0289d9b1b0d99258e66e6283993764102",
"md5": "96be77ace1b3ac555a23f3bdf0d3e087",
"sha256": "ab36a59db42c1682addb0d2670bf127288956c8a74dbeb988c3753bd76dc75dd"
},
"downloads": -1,
"filename": "mdfile-0.9.0.tar.gz",
"has_sig": false,
"md5_digest": "96be77ace1b3ac555a23f3bdf0d3e087",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.15,>=3.10",
"size": 22514,
"upload_time": "2025-08-19T04:12:46",
"upload_time_iso_8601": "2025-08-19T04:12:46.441559Z",
"url": "https://files.pythonhosted.org/packages/ec/95/ee268b114170b2c1357badb45ca0289d9b1b0d99258e66e6283993764102/mdfile-0.9.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-19 04:12:46",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "hucker",
"github_project": "mdfile",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "mdfile"
}
