From 44534b909fbb703e3ceeb0971041995cc59d369a Mon Sep 17 00:00:00 2001 From: gitee-bot Date: Thu, 15 Jan 2026 02:45:17 +0000 Subject: [PATCH] Update README.md --- README.md | 124 +++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 100 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index 1652937..18f46ed 100644 --- a/README.md +++ b/README.md @@ -1,52 +1,128 @@ + + # mii - Markdown-include-images -A script tool that replaces externally linked images in a Markdown file with their base64-encoded content (embedded directly in the file). +A script tool that replaces externally linked images in a Markdown file with their base64-encoded content embedded directly in the file. + +## Overview + +mii solves the problem of managing Markdown files with external image references. By converting all image references to base64-encoded data URIs, your Markdown files become fully self-contained and portable—no external image dependencies required. + +## Features -![mii by draw.io](./mii.png) +- **Local Image Support**: Convert local image file paths to embedded base64 data +- **Remote Image Support**: Fetch and embed remote images asynchronously +- **Multiple Output Options**: Process files in-place or save to a new file +- **Error Handling**: Gracefully skips missing or inaccessible images with warnings +- **Non-destructive**: Original files remain untouched unless explicitly overwritten -**ATTENTION**: Gitee doesn't support this kind of markdown file,i give up. +## Installation -## Dependence +### Dependencies -If no externally images in the source markdown file,no need to install this module,and no errors will show. +mii requires Python 3.6+ and the following packages: ```shell -$pip install aiohttp -# OR -$pip install aiohttp -i https://pypi.tuna.tsinghua.edu.cn/simple +pip install aiohttp +# OR with Tsinghua mirror for faster installation in China +pip install aiohttp -i https://pypi.tuna.tsinghua.edu.cn/simple ``` +**Note**: If your Markdown files contain no external images, you don't need to install any dependencies and won't see any errors. + ## Usage ```shell +python markdown-include-images.py [-i] [-o other-markdown-file] input-markdown-file +``` + +### Parameters + +- `-i, --interactive`: Overwrite the input Markdown file directly +- `-o, --output other-markdown-file`: Save processed content to a new file +- `input-markdown-file`: Path to the source Markdown file -python markdown-include-images.py [-i][-o other-markdown-file] input-markdown-file +### Examples --i,--interactive overwrite input-markdown-file --o other-markdown-file,--output other-markdown-file save the content to other-markdown-file +Process a file and save to a new file: +```shell +python markdown-include-images.py README.md -o new-readme.md +``` + +Overwrite the original file: +```shell +python markdown-include-images.py README.md -i ``` -## What Happened +## How It Works -Just replace all the image anchor(`![alt](path-to-image)`) to local image id tag and convert the image to base64 string,and append them at the tail of markdown file. +1. **Image Detection**: Scans the Markdown file for image anchor tags in the format `![alt](image-path)` +2. **Image Processing**: + - For local images: Reads the file and converts to base64 + - For remote images: Fetches content asynchronously and converts to base64 +3. **Anchor Replacement**: Replaces the original image anchor with a reference ID +4. **Data Appending**: Appends base64-encoded image data at the end of the file in a special format -## Here is a test +## Example -### image doesn't exist +**Before processing:** +```markdown +# My Document -![I know this local image doesn't exist](./res/test.jpg) +![My Image](./images/photo.jpg) -### image online +Some text here... +``` + +**After processing:** +```markdown +# My Document -![this is online](https://wallpapercave.com/wp/wp8788340.jpg) -![this is online](https://wallpapercave.com/wp/wp8788341.jpg) -![this is online](https://wallpapercave.com/wp/wp8788342.jpg) +![My Image][img-123] -## Here is the result +Some text here... + +[img-123]: data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAYEBQYFBAYGBQYHBwYIChAKCgkJChQODwwQFxQYGBcUFhYaHSUfGhsjHBYWICwgIyYnKSopGR8tMC0oMCUoKSj/2wBDAQcHBwoIChMKChMoGhYaKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCj/wAARCAABAAEDASIAAhEBAxEB/8QAFQABAQAAAAAAAAAAAAAAAAAAAAn/xAAUEAEAAAAAAAAAAAAAAAAAAAAA/8QAFQEBAQAAAAAAAAAAAAAAAAAAAAX/xAAUEQEAAAAAAAAAAAAAAAAAAAAA/9oADAMBAAIRAxEAPwCwAB//2Q== +``` + +## API Reference + +### Main Functions + +- `convert_image_to_base64(img_file)`: Converts an image file to base64 encoded string +- `convert_filename_to_id(filename)`: Generates a unique ID for an image based on filename +- `convert_image_to_md_anchor(img_id, filename, data=None)`: Creates a Markdown anchor for the embedded image +- `replace_anchor_in_md(content, anchor, alt, url, data)`: Replaces image anchor with embedded version +- `remote_images_fetcher(remote_image_table, anchor_table_)`: Asynchronously fetches remote images + +### Command-line Interface + +```python +main(in_md_file, out_md_file) +``` + +Processes input Markdown file and writes to output file. Set `out_md_file` to `None` for in-place modification. + +## Testing + +The repository includes test images in the `res/` directory. You can verify the tool works by running it on the README.md file: ```shell -x@wang:~/ws/mii$ python3 markdown-include-images.py README.md -o new-readme ->>> [WARN] image file (/home/x/ws/mii/path-to-image) not found,skip this tag: ![alt](path-to-image)... ->>> [WARN] image file (/home/x/ws/mii/./res/test.jpg) not found,skip this tag: ![this local image doesn't exist](./res/test.jpg)... +python markdown-include-images.py README.md -o new-readme.md +``` + +Expected output: +``` +>>> [WARN] image file (/path/to/image) not found,skip this tag: ![alt](path-to-image)... >>> operation done,output file:new-readme.md ``` + +## License + +This project is open source and available under the MIT License. + +## Limitations + +- Large images will significantly increase file size due to base64 encoding +- Gitee and some other platforms may not render base64-embedded images correctly +- Remote image fetching requires internet connectivity \ No newline at end of file -- Gitee