<h1 align="center">
imarkdown
</h1>
<p align="center">
<strong>imarkdown is a lightweight markdown image link converter that allows you to easily convert image links between local and image server, as well as between different image servers.</strong>
</p>
[English](/README.md) [中文](/README_zh.md)
> When converting markdown from Yuque, the images are protected against external linking. If you want to publish the converted markdown on other platforms, you need to change all the image addresses in the markdown to local image addresses or custom image server addresses, so that others can view them correctly. This project aims to solve this problem by providing a converter that can batch convert image links in markdown and supports customized conversion in complex scenarios.
## Features
- Batch Download: imarkdown can batch download all the images in the markdown that are referenced using image links.
- Multiple Conversion Methods: imarkdown supports various conversion methods for image links in markdown, such as converting to local image, converting web URL to local image, and converting web URL to image server URL.
- Batch Conversion: It supports batch conversion of single or multiple files, as well as formatting and renaming of generated files.
- Highly Customizable: By inheriting the `MdAdapter` class, you can easily implement custom URL conversion for different image servers.
- Image Server Adapters: Currently, only Aliyun OSS is supported as an image server. Contributions are welcome to add support for more types of image servers.
- Custom recognition format: With ElementFinder, users can customize the search method for elements (such as image addresses) to meet the needs of special element recognition.
## Target Audience
- People who need to batch convert image links in markdown.
- Users who export markdown from Yuque and need to convert image links.
- People who need to develop third-party extensions.
## Technical Architecture
`imarkdown` is designed with a modular architecture, allowing easy extension of each component. The following diagram provides a simplified overview of the technical architecture of imarkdown, which consists of the following components:
- `MdImageConverter`: The image converter responsible for converting the image addresses in markdown and generating new markdown files.
- `MdAdapter`: The adapter for converting `Image` objects to different types, such as `LocalFileAdapter` for local conversion, `AliyunAdapter` for Aliyun OSS conversion, and `CustomAdapter` for custom conversion. By injecting the adapter into `MdImageConverter`, you can define the type of address to convert `Image` objects to.
- `MdMedium`: Includes `MdFile` and `MdFolder`, encapsulating some features used for data conversion in `MdImageConverter`.
<img src="https://zeeland-bucket.oss-cn-beijing.aliyuncs.com/images/20230713154424.png"/>
The execution process of `imarkdown` is roughly as follows: after the `convert` method is called on `MdImageConverter`, `imarkdown` builds a virtual `MdTree` based on the provided `MdMedium`, and performs batch image URL conversion on the files according to this tree.
<img src="https://zeeland-bucket.oss-cn-beijing.aliyuncs.com/images/20230713155912.png"/>
## Quick Start
This project is developed in Python and distributed on PyPI. Users can easily use imarkdown by installing it with pip. The following sections will explain several usage scenarios and methods of imarkdown.
- Third-Party Package Installation: Open a terminal or command prompt and run the following command.
```sh
pip install -U imarkdown
```
**Examples**
- [Convert Web URLs to Local Addresses](#converting-web-urls-to-local-file-paths)
- [Convert Web URLs to Image Server URLs](#converting-web-urls-to-image-hosting-service-urls)
- [Batch Conversion: Web URLs to Local](#batch-conversion-of-multiple-files-web-url-to-local)
- [Batch Conversion: Local to Image Server](#batch-conversion-of-multiple-files-local-to-image-hosting-service)
- [Custom Image Hosting Service](#custom-image-hosting-service)
### Converting Web URLs to Local File Paths
If you have web URL links for images in your Markdown file and you want to download them in bulk to your local machine while converting the image addresses in Markdown to local file paths, the following example will solve your problem.
Assuming the file you want to convert is `test.md` with the following content:
> The examples below will be based on the initial Markdown file if it is a web URL. They are not repeated here.
```text
## 6.3 Converting MD Image Addresses
Only supports uploading to a local image hosting service.
- [https://github.com/JyHu/useful_script.git](https://github.com/JyHu/useful_script.git)
- [https://github.com/JyHu/useful_script/blob/](https://github.com/JyHu/useful_script/blob/master/Scripts/md%E6%96%87%E4%BB%B6%E5%9B%BE%E7%89%87%E5%9B%BE%E5%BA%8A%E8%BD%AC%E6%8D%A2/%E8%87%AA%E5%8A%A8%E8%BD%AC%E6%8D%A2markdown%E6%96%87%E4%BB%B6%E4%B8%AD%E5%9B%BE%E7%89%87%E5%88%B0%E5%9B%BE%E5%BA%8A.md/)
After all the hassle and trying this, I found it doesn't work either.
In the end, PigGo is still the best. It provides a shortcut for uploading, and after uploading, you can directly xxxTODO.
## 6.4 Pycasbin
In pycasbin, I saw a colleague who frequently contributes to pycasbin. You can refer to some of his contributions:
- [https://github.com/Nekotoxin/nekotoxin.github.io/blob/gsoc_2022_summary/GSoC2022-summary.md](https://github.com/Nekotoxin/nekotoxin.github.io/blob/gsoc_2022_summary/GSoC2022-summary.md)
```
This content is the exported Markdown file from Yuque, and its image links are protected against external access. They need to be downloaded and replaced with local file paths in the Markdown.
```python
from imarkdown import MdFile, LocalFileAdapter, MdImageConverter
def main():
adapter = LocalFileAdapter()
converter = MdImageConverter(adapter=adapter)
md_file = MdFile(name="test.md")
converter.convert(md_file)
if __name__ == '__main__':
main()
```
> In imarkdown, there are many places where you need to provide paths. You can use relative paths or absolute paths. It is recommended to use `/` as the path separator instead of `\\`.
The converted result will generate a new Markdown file named `test_converted.md`, with the following content:
```text
## 6.3 Converting MD Image Addresses
Only supports uploading to a local image hosting service.
- [https://github.com/JyHu/useful_script.git](https://github.com/JyHu/useful_script.git)
- [https://github.com/JyHu/useful_script/blob/](https://github.com/JyHu/useful_script/blob/master/Scripts/md%E6%96%87%E4%BB%B6%E5%9B%BE%E7%89%87%E5%9B%BE%E5%BA%8A%E8%BD%AC%E6%8D%A2/%E8%87%AA%E5%8A%A8%E8%BD%AC%E6%8D%A2markdown%E6%96%87%E4%BB%B6%E4%B8%AD%E5%9B%BE%E7%89%87%E5%88%B0%E5%9B%BE%E5%BA%8A.md/)
After all the hassle and trying this, I found it doesn't work either.
In the end, PigGo is still the best. It provides a shortcut for uploading, and after uploading, you can directly xxxTODO.
## 6.4 Pycasbin
In pycasbin, I saw a colleague who frequently contributes to pycasbin. You can refer to some of his contributions:
- [https://github.com/Nekotoxin/nekotoxin.github.io/blob/gsoc_2022_summary/GSoC2022-summary.md](https://github.com/Nekotoxin/nekotoxin.github.io/blob/gsoc_2022_summary/GSoC2022-summary.md)
```
- Customizing the Output File Name
When using imarkdown for conversion, the default name for the converted Markdown file is `{markdown_file_name}_converted.md`. If you want to customize the output file name, you can use the following configuration:
```python
md_converter.convert(md_file, name_prefix="new_", name_suffix="_converted")
```
Using this method of conversion will result in a file named `new_test_converted.md`. If you want to completely customize the converted name, you can use the following method:
```python
md_converter.convert(md_file, new_name="A new markdown.md")
```
With the above method, a file named `A new markdown.md` will be generated.
### Converting Web URLs to Image Hosting Service URLs
In the following example, we will use the `test.md` file provided earlier to demonstrate the conversion of image addresses from web URLs to URLs on the Alibaba Cloud OSS server, showcasing the functionality of converting web URLs to image hosting service URLs.
```python
from imarkdown import MdImageConverter, AliyunAdapter, MdFile
def main():
aliyun_config = {
"access_key_id": "key_id",
"access_key_secret": "key_secret",
"bucket_name": "bucket_name",
"place": "bucket_place",
"storage_path_prefix": "prefix",
}
adapter = AliyunAdapter(**aliyun_config)
md_converter = MdImageConverter(adapter=adapter)
md_file = MdFile(name="markdown.md")
md_converter.convert(md_file)
if __name__ == "__main__":
main()
```
In the example above, `storage_path_prefix` represents the file prefix in the bucket where the image is uploaded to OSS. If you want to store the image in the `/imarkdown` directory, you need to set `storage_path_prefix="/imarkdown"`. The remaining configuration details are specific to Alibaba Cloud OSS, so please fill them in accordingly.
### Batch Conversion of Multiple Files: Web URL to Local
The following example demonstrates a solution for batch conversion of multiple Markdown files, converting web image URLs to local image addresses.
```python
from imarkdown import LocalFileAdapter, MdFolder, MdImageConverter
def main():
adapter = LocalFileAdapter()
converter = MdImageConverter(adapter=adapter)
# Folder name is "mds"
md_folder = MdFolder(name="mds")
# Output files to "converted_mds"
converter.convert(md_folder, output_directory="converted_mds")
```
Using the above code snippet will create a folder named "converted_mds" where the converted files will be saved. The images will be saved in the `converted_mds/images` directory. If you want to output the images to a specific folder, you can set it as follows:
```python
md_folder = MdFolder(name="mds", image_directory="mds/my_images")
```
### Batch Conversion of Multiple Files: Local to Image Hosting Service
The following example demonstrates a solution for batch conversion of multiple Markdown files, converting local image addresses to image hosting service URLs.
```python
from imarkdown import LocalFileAdapter, MdFolder, MdImageConverter
def main():
adapter = LocalFileAdapter()
converter = MdImageConverter(adapter=adapter)
# Folder name is "local_mds", images are of local type, and image URLs are saved in "local_mds/images"
md_folder = MdFolder(name="local_mds", image_type="local", image_directory="local_mds/images")
# Output files to "converted_mds"
converter.convert(md_folder, output_directory="converted_mds")
```
### Custom Image Hosting Service
The following example demonstrates how to use imarkdown to upload images to a custom file server and retrieve the URL.
First, you need to create a custom adapter by inheriting from `BaseMdAdapter` and implementing the `upload` and `get_replaced_url` methods. Then, you can inject the custom adapter into `MdImageConverter`.
```python
import os
import json
import requests
from imarkdown import BaseMdAdapter, MdImageConverter, MdFolder
class CustomMdAdapter(BaseMdAdapter):
name = "custom"
url = "https://server/upload/file/batch"
headers = {
"X-Upload-Token": "my_token"
}
cur_key = ""
def upload(self, key: str, file):
files = {"file": file}
response = requests.post(self.url, headers=self.headers, files=files)
if response.status_code == 200:
res_data = json.loads(response.content.decode("utf-8"))
self.cur_key = res_data["data"]["images"]["url"]
else:
raise Exception(response.content)
def get_replaced_url(self, key):
return self.cur_key
def get_all_folder_names():
return os.listdir("my-blog")
def main():
adapter = CustomMdAdapter()
md_converter = MdImageConverter(adapter=adapter)
md_folders = []
for folder_name in get_all_folder_names():
md_folders.append(
MdFolder(
name=f"my-blog/{folder_name}",
image_directory=f"my-blog/{folder_name}/images",
image_type="local",
)
)
md_converter.convert(md_folders, output_directory="converted")
if __name__ == "__main__":
main()
```
### Custom Regular Expression
`imarkdown` uses the regular expression element finder `ReElementFinder` to recognize the URL of an image, the finder currently supports `` and `<img src="image_url"/>` are two types of image URL format recognition. Of course, if your image URL is strange, sometimes the default regular expression for `imarkdown` cannot be recognized.
At this point, you can customize an element finder called `CustomElementFinder`, which can recognize the content you need to recognize through custom regular expressions or other recognition methods, and use it to pass it to MdImageConverter for element replacement. The following example shows how to use a custom `ElementFinder` to identify image links.
```python
import re
from typing import List
from imarkdown import BaseElementFinder, MdFile, MdImageConverter, LocalFileAdapter
class CustomElementFinder(BaseElementFinder):
def find_all_elements(self, md_str) -> List[str]:
re_rule: str = r"(?:!\[(.*?)\]\((.*?)\))|<img.*?src=[\'\"](.*?)[\'\"].*?>"
images = re.findall(re_rule, md_str)
return list(map(lambda item: item[1], images))
def main():
adapter = LocalFileAdapter()
converter = MdImageConverter(adapter=adapter)
element_finder = CustomElementFinder()
md_file = MdFile(name="test.md")
converter.convert(md_file, element_finder=element_finder)
if __name__ == "__main__":
main()
```
In this example, `CustomElementFinder` needs to inherit from `BaseElementFinder` and implement `find_all_elements()` function and implements specific search logic to construct an array of all elements found in the markdown (such as the urls of all images) and return it to `MdImageConverter`.
## Roadmap
- [ ] Add client-side support
- [ ] Support Tencent Cloud, Qiniu Cloud, and other image hosting services
- [x] Support batch file modification
- [x] Custom adapters
- [ ] Support compression of large images
- [ ] Support command-line interface
- [x] Support PyPI for simplified operations
- [ ] Provide file custom naming
- [ ] Provide custom formatting for image names
## FAQ
**1. How can I extend to other image hosting services?**
If you want to develop support for other image hosting services, all you need to do is implement an adapter similar to `AliyunAdapter` and inject it into `MdImageConverter` when using it. Refer to [Custom Image Hosting Service](#custom-image-hosting-service). That's all you need to do. In fact, I've wrapped it up nicely, so extending it is straightforward.
**2. Usage of file addresses**
In Python, both `/` and `\\` can be used as file path separators. However, there are some differences in their usage.
- `/` (forward slash): In most operating systems, including Windows, Linux, and Mac, `/` is used as the file path separator. Using `/` as the separator can make your code portable across different operating systems. For example:
```python
path = "folder/file.txt"
```
- `\\` (backslash): In the Windows operating system, `\\` is used as the file path separator. This is because `\` is used as an escape character in Windows, so to represent a plain backslash, you need to use two consecutive backslashes. For example:
```python
path = "folder\\file.txt"
```
When using `\\` as the separator, keep the following points in mind:
- When using `\\` in a string, you need to escape it as `\\\\` because the first `\` will be interpreted as an escape character.
- You can use raw strings to avoid the hassle of escaping. In a raw string, `\` is not interpreted as an escape character. For example: `path = r"folder\file.txt"`
In summary, if your code needs to run on different operating systems, it is recommended to use `/` as the file path separator to maintain code portability. If you are only running the code on Windows, using `\\` is also acceptable. However, in `imarkdown`, all `\\` paths will be converted to `/`. In this project, all `\\` paths will be converted to `/`.
## Contribution
Contributions are welcome! If you would like to contribute to this project, you can submit a pull request or an issue. There are some extensible features listed in the [Development Roadmap](#development-roadmap), and there are still many third-party image hosting services that need to be adapted. If you are working on these aspects, feel free to submit a pull request! I'm excited to see more people involved in improving and optimizing it.
Raw data
{
"_id": null,
"home_page": "https://github.com/Undertone0809/imarkdown",
"name": "imarkdown",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "Markdown,markdown,imarkdown,markdown converter",
"author": "Zeeland",
"author_email": "zeeland@foxmail.com",
"download_url": "https://files.pythonhosted.org/packages/8b/f1/a464a7316f1b7ae27c6db26c8e900d94ee0e9d5a141943520f6a92d6d811/imarkdown-1.2.2.tar.gz",
"platform": null,
"description": "<h1 align=\"center\">\r\n imarkdown\r\n</h1>\r\n<p align=\"center\">\r\n <strong>imarkdown is a lightweight markdown image link converter that allows you to easily convert image links between local and image server, as well as between different image servers.</strong>\r\n</p>\r\n\r\n[English](/README.md) [\u4e2d\u6587](/README_zh.md)\r\n\r\n> When converting markdown from Yuque, the images are protected against external linking. If you want to publish the converted markdown on other platforms, you need to change all the image addresses in the markdown to local image addresses or custom image server addresses, so that others can view them correctly. This project aims to solve this problem by providing a converter that can batch convert image links in markdown and supports customized conversion in complex scenarios.\r\n\r\n## Features\r\n\r\n- Batch Download: imarkdown can batch download all the images in the markdown that are referenced using image links.\r\n- Multiple Conversion Methods: imarkdown supports various conversion methods for image links in markdown, such as converting to local image, converting web URL to local image, and converting web URL to image server URL.\r\n- Batch Conversion: It supports batch conversion of single or multiple files, as well as formatting and renaming of generated files.\r\n- Highly Customizable: By inheriting the `MdAdapter` class, you can easily implement custom URL conversion for different image servers.\r\n- Image Server Adapters: Currently, only Aliyun OSS is supported as an image server. Contributions are welcome to add support for more types of image servers.\r\n- Custom recognition format: With ElementFinder, users can customize the search method for elements (such as image addresses) to meet the needs of special element recognition.\r\n\r\n## Target Audience\r\n\r\n- People who need to batch convert image links in markdown.\r\n- Users who export markdown from Yuque and need to convert image links.\r\n- People who need to develop third-party extensions.\r\n\r\n## Technical Architecture\r\n\r\n`imarkdown` is designed with a modular architecture, allowing easy extension of each component. The following diagram provides a simplified overview of the technical architecture of imarkdown, which consists of the following components:\r\n\r\n- `MdImageConverter`: The image converter responsible for converting the image addresses in markdown and generating new markdown files.\r\n- `MdAdapter`: The adapter for converting `Image` objects to different types, such as `LocalFileAdapter` for local conversion, `AliyunAdapter` for Aliyun OSS conversion, and `CustomAdapter` for custom conversion. By injecting the adapter into `MdImageConverter`, you can define the type of address to convert `Image` objects to.\r\n- `MdMedium`: Includes `MdFile` and `MdFolder`, encapsulating some features used for data conversion in `MdImageConverter`.\r\n\r\n\r\n<img src=\"https://zeeland-bucket.oss-cn-beijing.aliyuncs.com/images/20230713154424.png\"/>\r\n\r\nThe execution process of `imarkdown` is roughly as follows: after the `convert` method is called on `MdImageConverter`, `imarkdown` builds a virtual `MdTree` based on the provided `MdMedium`, and performs batch image URL conversion on the files according to this tree.\r\n\r\n<img src=\"https://zeeland-bucket.oss-cn-beijing.aliyuncs.com/images/20230713155912.png\"/>\r\n\r\n## Quick Start\r\n\r\nThis project is developed in Python and distributed on PyPI. Users can easily use imarkdown by installing it with pip. The following sections will explain several usage scenarios and methods of imarkdown.\r\n\r\n- Third-Party Package Installation: Open a terminal or command prompt and run the following command.\r\n\r\n```sh\r\npip install -U imarkdown\r\n```\r\n\r\n**Examples**\r\n- [Convert Web URLs to Local Addresses](#converting-web-urls-to-local-file-paths)\r\n- [Convert Web URLs to Image Server URLs](#converting-web-urls-to-image-hosting-service-urls)\r\n- [Batch Conversion: Web URLs to Local](#batch-conversion-of-multiple-files-web-url-to-local)\r\n- [Batch Conversion: Local to Image Server](#batch-conversion-of-multiple-files-local-to-image-hosting-service)\r\n- [Custom Image Hosting Service](#custom-image-hosting-service)\r\n\r\n\r\n### Converting Web URLs to Local File Paths\r\n\r\nIf you have web URL links for images in your Markdown file and you want to download them in bulk to your local machine while converting the image addresses in Markdown to local file paths, the following example will solve your problem.\r\n\r\nAssuming the file you want to convert is `test.md` with the following content:\r\n\r\n> The examples below will be based on the initial Markdown file if it is a web URL. They are not repeated here.\r\n\r\n```text\r\n## 6.3 Converting MD Image Addresses\r\nOnly supports uploading to a local image hosting service.\r\n\r\n- [https://github.com/JyHu/useful_script.git](https://github.com/JyHu/useful_script.git)\r\n- [https://github.com/JyHu/useful_script/blob/](https://github.com/JyHu/useful_script/blob/master/Scripts/md%E6%96%87%E4%BB%B6%E5%9B%BE%E7%89%87%E5%9B%BE%E5%BA%8A%E8%BD%AC%E6%8D%A2/%E8%87%AA%E5%8A%A8%E8%BD%AC%E6%8D%A2markdown%E6%96%87%E4%BB%B6%E4%B8%AD%E5%9B%BE%E7%89%87%E5%88%B0%E5%9B%BE%E5%BA%8A.md/)\r\n\r\nAfter all the hassle and trying this, I found it doesn't work either.\r\n\r\n\r\nIn the end, PigGo is still the best. It provides a shortcut for uploading, and after uploading, you can directly xxxTODO.\r\n\r\n## 6.4 Pycasbin\r\n\r\nIn pycasbin, I saw a colleague who frequently contributes to pycasbin. You can refer to some of his contributions:\r\n\r\n- [https://github.com/Nekotoxin/nekotoxin.github.io/blob/gsoc_2022_summary/GSoC2022-summary.md](https://github.com/Nekotoxin/nekotoxin.github.io/blob/gsoc_2022_summary/GSoC2022-summary.md)\r\n\r\n\r\n\r\n```\r\n\r\nThis content is the exported Markdown file from Yuque, and its image links are protected against external access. They need to be downloaded and replaced with local file paths in the Markdown.\r\n\r\n```python\r\nfrom imarkdown import MdFile, LocalFileAdapter, MdImageConverter\r\n\r\ndef main():\r\n adapter = LocalFileAdapter()\r\n converter = MdImageConverter(adapter=adapter)\r\n \r\n md_file = MdFile(name=\"test.md\")\r\n converter.convert(md_file)\r\n\r\nif __name__ == '__main__':\r\n main()\r\n```\r\n\r\n> In imarkdown, there are many places where you need to provide paths. You can use relative paths or absolute paths. It is recommended to use `/` as the path separator instead of `\\\\`.\r\n\r\nThe converted result will generate a new Markdown file named `test_converted.md`, with the following content:\r\n\r\n```text\r\n## 6.3 Converting MD Image Addresses\r\nOnly supports uploading to a local image hosting service.\r\n\r\n- [https://github.com/JyHu/useful_script.git](https://github.com/JyHu/useful_script.git)\r\n- [https://github.com/JyHu/useful_script/blob/](https://github.com/JyHu/useful_script/blob/master/Scripts/md%E6%96%87%E4%BB%B6%E5%9B%BE%E7%89%87%E5%9B%BE%E5%BA%8A%E8%BD%AC%E6%8D%A2/%E8%87%AA%E5%8A%A8%E8%BD%AC%E6%8D%A2markdown%E6%96%87%E4%BB%B6%E4%B8%AD%E5%9B%BE%E7%89%87%E5%88%B0%E5%9B%BE%E5%BA%8A.md/)\r\n\r\nAfter all the hassle and trying this, I found it doesn't work either.\r\n\r\n\r\nIn the end, PigGo is still the best. It provides a shortcut for uploading, and after uploading, you can directly xxxTODO.\r\n\r\n## 6.4 Pycasbin\r\n\r\nIn pycasbin, I saw a colleague who frequently contributes to pycasbin. You can refer to some of his contributions:\r\n\r\n- [https://github.com/Nekotoxin/nekotoxin.github.io/blob/gsoc_2022_summary/GSoC2022-summary.md](https://github.com/Nekotoxin/nekotoxin.github.io/blob/gsoc_2022_summary/GSoC2022-summary.md)\r\n\r\n\r\n\r\n```\r\n\r\n- Customizing the Output File Name\r\nWhen using imarkdown for conversion, the default name for the converted Markdown file is `{markdown_file_name}_converted.md`. If you want to customize the output file name, you can use the following configuration:\r\n\r\n```python\r\nmd_converter.convert(md_file, name_prefix=\"new_\", name_suffix=\"_converted\")\r\n```\r\n\r\nUsing this method of conversion will result in a file named `new_test_converted.md`. If you want to completely customize the converted name, you can use the following method:\r\n\r\n```python\r\nmd_converter.convert(md_file, new_name=\"A new markdown.md\")\r\n```\r\n\r\nWith the above method, a file named `A new markdown.md` will be generated.\r\n\r\n### Converting Web URLs to Image Hosting Service URLs\r\n\r\nIn the following example, we will use the `test.md` file provided earlier to demonstrate the conversion of image addresses from web URLs to URLs on the Alibaba Cloud OSS server, showcasing the functionality of converting web URLs to image hosting service URLs.\r\n\r\n```python\r\nfrom imarkdown import MdImageConverter, AliyunAdapter, MdFile\r\n\r\n\r\ndef main():\r\n aliyun_config = {\r\n \"access_key_id\": \"key_id\",\r\n \"access_key_secret\": \"key_secret\",\r\n \"bucket_name\": \"bucket_name\",\r\n \"place\": \"bucket_place\",\r\n \"storage_path_prefix\": \"prefix\",\r\n }\r\n adapter = AliyunAdapter(**aliyun_config)\r\n md_converter = MdImageConverter(adapter=adapter)\r\n md_file = MdFile(name=\"markdown.md\")\r\n md_converter.convert(md_file)\r\n\r\n\r\nif __name__ == \"__main__\":\r\n main()\r\n```\r\n\r\nIn the example above, `storage_path_prefix` represents the file prefix in the bucket where the image is uploaded to OSS. If you want to store the image in the `/imarkdown` directory, you need to set `storage_path_prefix=\"/imarkdown\"`. The remaining configuration details are specific to Alibaba Cloud OSS, so please fill them in accordingly.\r\n\r\n\r\n### Batch Conversion of Multiple Files: Web URL to Local\r\n\r\nThe following example demonstrates a solution for batch conversion of multiple Markdown files, converting web image URLs to local image addresses.\r\n\r\n```python\r\nfrom imarkdown import LocalFileAdapter, MdFolder, MdImageConverter\r\n\r\ndef main():\r\n adapter = LocalFileAdapter()\r\n converter = MdImageConverter(adapter=adapter)\r\n \r\n # Folder name is \"mds\"\r\n md_folder = MdFolder(name=\"mds\")\r\n # Output files to \"converted_mds\"\r\n converter.convert(md_folder, output_directory=\"converted_mds\")\r\n```\r\n\r\nUsing the above code snippet will create a folder named \"converted_mds\" where the converted files will be saved. The images will be saved in the `converted_mds/images` directory. If you want to output the images to a specific folder, you can set it as follows:\r\n\r\n```python\r\nmd_folder = MdFolder(name=\"mds\", image_directory=\"mds/my_images\")\r\n```\r\n\r\n### Batch Conversion of Multiple Files: Local to Image Hosting Service\r\n\r\nThe following example demonstrates a solution for batch conversion of multiple Markdown files, converting local image addresses to image hosting service URLs.\r\n\r\n```python\r\nfrom imarkdown import LocalFileAdapter, MdFolder, MdImageConverter\r\n\r\ndef main():\r\n adapter = LocalFileAdapter()\r\n converter = MdImageConverter(adapter=adapter)\r\n \r\n # Folder name is \"local_mds\", images are of local type, and image URLs are saved in \"local_mds/images\"\r\n md_folder = MdFolder(name=\"local_mds\", image_type=\"local\", image_directory=\"local_mds/images\")\r\n # Output files to \"converted_mds\"\r\n converter.convert(md_folder, output_directory=\"converted_mds\")\r\n```\r\n\r\n### Custom Image Hosting Service\r\n\r\nThe following example demonstrates how to use imarkdown to upload images to a custom file server and retrieve the URL.\r\n\r\nFirst, you need to create a custom adapter by inheriting from `BaseMdAdapter` and implementing the `upload` and `get_replaced_url` methods. Then, you can inject the custom adapter into `MdImageConverter`.\r\n\r\n```python\r\nimport os\r\nimport json\r\n\r\nimport requests\r\nfrom imarkdown import BaseMdAdapter, MdImageConverter, MdFolder\r\n\r\nclass CustomMdAdapter(BaseMdAdapter):\r\n name = \"custom\"\r\n url = \"https://server/upload/file/batch\"\r\n headers = {\r\n \"X-Upload-Token\": \"my_token\"\r\n }\r\n cur_key = \"\"\r\n\r\n def upload(self, key: str, file):\r\n files = {\"file\": file}\r\n response = requests.post(self.url, headers=self.headers, files=files)\r\n if response.status_code == 200:\r\n res_data = json.loads(response.content.decode(\"utf-8\"))\r\n self.cur_key = res_data[\"data\"][\"images\"][\"url\"]\r\n else:\r\n raise Exception(response.content)\r\n\r\n def get_replaced_url(self, key):\r\n return self.cur_key\r\n\r\ndef get_all_folder_names():\r\n return os.listdir(\"my-blog\")\r\n\r\n \r\ndef main():\r\n adapter = CustomMdAdapter()\r\n md_converter = MdImageConverter(adapter=adapter)\r\n\r\n md_folders = []\r\n for folder_name in get_all_folder_names():\r\n md_folders.append(\r\n MdFolder(\r\n name=f\"my-blog/{folder_name}\",\r\n image_directory=f\"my-blog/{folder_name}/images\",\r\n image_type=\"local\",\r\n )\r\n )\r\n md_converter.convert(md_folders, output_directory=\"converted\")\r\n\r\n\r\nif __name__ == \"__main__\":\r\n main()\r\n```\r\n\r\n### Custom Regular Expression\r\n\r\n`imarkdown` uses the regular expression element finder `ReElementFinder` to recognize the URL of an image, the finder currently supports `` and `<img src=\"image_url\"/>` are two types of image URL format recognition. Of course, if your image URL is strange, sometimes the default regular expression for `imarkdown` cannot be recognized.\r\n\r\nAt this point, you can customize an element finder called `CustomElementFinder`, which can recognize the content you need to recognize through custom regular expressions or other recognition methods, and use it to pass it to MdImageConverter for element replacement. The following example shows how to use a custom `ElementFinder` to identify image links.\r\n\r\n```python\r\nimport re\r\nfrom typing import List\r\n\r\nfrom imarkdown import BaseElementFinder, MdFile, MdImageConverter, LocalFileAdapter\r\n\r\n\r\nclass CustomElementFinder(BaseElementFinder):\r\n def find_all_elements(self, md_str) -> List[str]:\r\n re_rule: str = r\"(?:!\\[(.*?)\\]\\((.*?)\\))|<img.*?src=[\\'\\\"](.*?)[\\'\\\"].*?>\"\r\n images = re.findall(re_rule, md_str)\r\n return list(map(lambda item: item[1], images))\r\n\r\n\r\ndef main():\r\n adapter = LocalFileAdapter()\r\n converter = MdImageConverter(adapter=adapter)\r\n element_finder = CustomElementFinder()\r\n\r\n md_file = MdFile(name=\"test.md\")\r\n converter.convert(md_file, element_finder=element_finder)\r\n\r\n\r\nif __name__ == \"__main__\":\r\n main()\r\n```\r\n\r\nIn this example, `CustomElementFinder` needs to inherit from `BaseElementFinder` and implement `find_all_elements()` function and implements specific search logic to construct an array of all elements found in the markdown (such as the urls of all images) and return it to `MdImageConverter`.\r\n\r\n## Roadmap\r\n\r\n- [ ] Add client-side support\r\n- [ ] Support Tencent Cloud, Qiniu Cloud, and other image hosting services\r\n- [x] Support batch file modification\r\n- [x] Custom adapters\r\n- [ ] Support compression of large images\r\n- [ ] Support command-line interface\r\n- [x] Support PyPI for simplified operations\r\n- [ ] Provide file custom naming\r\n- [ ] Provide custom formatting for image names\r\n\r\n## FAQ\r\n\r\n**1. How can I extend to other image hosting services?**\r\n\r\nIf you want to develop support for other image hosting services, all you need to do is implement an adapter similar to `AliyunAdapter` and inject it into `MdImageConverter` when using it. Refer to [Custom Image Hosting Service](#custom-image-hosting-service). That's all you need to do. In fact, I've wrapped it up nicely, so extending it is straightforward.\r\n\r\n**2. Usage of file addresses**\r\n\r\nIn Python, both `/` and `\\\\` can be used as file path separators. However, there are some differences in their usage.\r\n\r\n- `/` (forward slash): In most operating systems, including Windows, Linux, and Mac, `/` is used as the file path separator. Using `/` as the separator can make your code portable across different operating systems. For example:\r\n\r\n```python\r\npath = \"folder/file.txt\"\r\n```\r\n\r\n- `\\\\` (backslash): In the Windows operating system, `\\\\` is used as the file path separator. This is because `\\` is used as an escape character in Windows, so to represent a plain backslash, you need to use two consecutive backslashes. For example:\r\n\r\n```python\r\npath = \"folder\\\\file.txt\"\r\n```\r\n\r\nWhen using `\\\\` as the separator, keep the following points in mind:\r\n\r\n- When using `\\\\` in a string, you need to escape it as `\\\\\\\\` because the first `\\` will be interpreted as an escape character.\r\n- You can use raw strings to avoid the hassle of escaping. In a raw string, `\\` is not interpreted as an escape character. For example: `path = r\"folder\\file.txt\"`\r\n\r\nIn summary, if your code needs to run on different operating systems, it is recommended to use `/` as the file path separator to maintain code portability. If you are only running the code on Windows, using `\\\\` is also acceptable. However, in `imarkdown`, all `\\\\` paths will be converted to `/`. In this project, all `\\\\` paths will be converted to `/`.\r\n\r\n## Contribution\r\n\r\nContributions are welcome! If you would like to contribute to this project, you can submit a pull request or an issue. There are some extensible features listed in the [Development Roadmap](#development-roadmap), and there are still many third-party image hosting services that need to be adapted. If you are working on these aspects, feel free to submit a pull request! I'm excited to see more people involved in improving and optimizing it.\r\n",
"bugtrack_url": null,
"license": "Apache 2.0",
"summary": "A practical Markdown image url converter",
"version": "1.2.2",
"project_urls": {
"Homepage": "https://github.com/Undertone0809/imarkdown"
},
"split_keywords": [
"markdown",
"markdown",
"imarkdown",
"markdown converter"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8bf1a464a7316f1b7ae27c6db26c8e900d94ee0e9d5a141943520f6a92d6d811",
"md5": "431cc263fd270e75b213bdadc3944078",
"sha256": "a4565c22fd85fda7daa7dd606fe46eee9a2e47c8be1113ec9ff7ef8017d16fa6"
},
"downloads": -1,
"filename": "imarkdown-1.2.2.tar.gz",
"has_sig": false,
"md5_digest": "431cc263fd270e75b213bdadc3944078",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 24650,
"upload_time": "2023-08-01T08:17:59",
"upload_time_iso_8601": "2023-08-01T08:17:59.186190Z",
"url": "https://files.pythonhosted.org/packages/8b/f1/a464a7316f1b7ae27c6db26c8e900d94ee0e9d5a141943520f6a92d6d811/imarkdown-1.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-01 08:17:59",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Undertone0809",
"github_project": "imarkdown",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "imarkdown"
}
JSON
