Documentation for plugins. (#94)

Author: vb64

README.md

@@ -6,7 +6,7 @@
 [![Codacy Badge](https://app.codacy.com/project/badge/Coverage/27b53043bff34f07bfb79ee1672b7ba0)](https://app.codacy.com/gh/vb64/markdown-pdf/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_coverage)
 [![PyPI - Downloads](https://img.shields.io/pypi/dm/markdown-pdf?label=pypi%20installs)](https://pypistats.org/packages/markdown-pdf)
 
-The free, open source Python module `markdown-pdf` will create a PDF file from your content in `markdown` format.
+The free, open source Python module `markdown-pdf` will create a PDF file from your `markdown` content.
 
 When creating a PDF file you can:
 
@@ -18,7 +18,7 @@ When creating a PDF file you can:
 - Use different page sizes within single pdf
 - Create tables in `markdown`
 - Use clickable hyperlinks. Thanks a lot [@thongtmtrust](https://github.com/thongtmtrust) for ideas and collaboration.
-- Use the plantuml content plugin
+- Render plantuml and mermaid code to pdf images with [plugins](plugins.md).
 
 The module utilizes the functions of two great libraries.
 
@@ -207,6 +207,8 @@ In the created file `plantuml.pdf`, you will see the following result:
 
 ![With plantuml.jpg](img/with_plantuml.jpg)
 
+You can find a more detailed description of the plugins [here](plugins.md).
+
 ## Example
 
 As an example, you can download the [pdf file](examples/markdown_pdf.pdf) created from this md file.

README_ru.md

@@ -12,7 +12,7 @@
 - Использовать разные размеры страниц внутри одного pdf
 - Создавать таблицы в `markdown`
 - Использовать кликабельные гиперссылки. Спасибо [@thongtmtrust](https://github.com/thongtmtrust) за идеи и сотрудничество!
-- Использовать плагин для контента plantuml
+- Преобразоввывать plantuml и mermaid код в картинки pdf при помощи [плагинов](plugins_ru.md).
 
 Модуль использует функции двух замечательных библиотек.
 
@@ -200,6 +200,8 @@ pdf.save("plantuml.pdf")
 
 ![With plantuml.jpg](img/with_plantuml.jpg)
 
+Вы можете ознакомиться с более подробным [описанием плагинов](plugins_ru.md).
+
 ## Пример
 
 В качестве примера вы можете загрузить созданный из этого md файла [pdf файл](examples/markdown_pdf_ru.pdf).

history.txt

@@ -3,6 +3,8 @@
 
 + Defaults for plantuml plugin.
 
++ Documentation for plugins.
+
 01.02.2026 ver.1.11
 -------------------
 

plugins.md

@@ -0,0 +1,84 @@
+# Plugins
+
+Markdown-pdf can process content marked with special code using plugins.
+A plugin can convert the code it's intended for into images or other content.
+
+You can use the following plugins out of the box with `markdown-pdf`.
+
+## plantuml
+
+The `plantuml` plugin replaces given code with an image of the corresponding diagram, generated using an external server (by default, `http://www.plantuml.com`).
+
+Your `markdown` document contains the following code snippet.
+
+````markdown
+```plantuml
+@startuml
+Alice -> Bob: Hello Bob
+Bob --> Alice: Hi!
+@enduml
+```
+````
+
+You can use a plugin to convert the diagram into an image.
+
+```python
+from markdown_pdf import MarkdownPdf, Section
+from markdown_pdf.pligins import Plugin
+
+plugins = {
+  # use defaults
+  Plugin.Plantuml: None
+  # or specify your server address
+  # Plugin.Plantuml: {'url': 'http://www.plantuml.com/plantuml/img/'}
+}
+
+pdf = MarkdownPdf(plugins=plugins)
+pdf.add_section(Section(markdown_text_with_plantuml_code))
+pdf.save("plantuml.pdf")
+```
+
+In the resulting PDF file, the code `plantuml` will be replaced with the following image.
+
+![plantuml.png](fixture/plantuml.png)
+
+## mermaid
+
+The `mermaid` plugin replaces code with an image generated by an external server (`https://mermaid.ink` by default).
+
+Your `markdown` document contains the following code snippet.
+
+````markdown
+```mermaid
+stateDiagram-v2
+    [*] --> Still
+    Still --> [*]
+
+    Still --> Moving
+    Moving --> Still
+    Moving --> Crash
+    Crash --> [*]
+```
+````
+
+You can use a plugin to convert this code into an image.
+
+```python
+from markdown_pdf import MarkdownPdf, Section
+from markdown_pdf.pligins import Plugin
+
+plugins = {
+  # use defaults
+  Plugin.Mermaid: None
+  # or specify your server address
+  # Plugin.Mermaid: {'url': 'https://mermaid.ink/img/'}
+}
+
+pdf = MarkdownPdf(plugins=plugins)
+pdf.add_section(Section(markdown_text_with_mermaid_code))
+pdf.save("mermaid.pdf")
+```
+
+In the resulting PDF file, the code `mermaid` will be replaced with the following image.
+
+![mermaid.png](fixture/mermaid.png)

plugins_ru.md

@@ -0,0 +1,84 @@
+# Плагины
+
+Markdown-pdf может обрабатывать помеченный специальным кодом контент при помощи плагинов.
+Плагин может преобразовывать предназначенный для него код в изображения или другой контент.
+
+В `markdown-pdf` вы можете использовать следующие плагины "из коробки".
+
+## plantuml
+
+Плагин для кода `plantuml` заменяет код на картинку соответствующей схемы, создаваемую при помощи внешнего сервера (по умолчанию `http://www.plantuml.com`).
+
+В вашем `markdown` документе имеется следующий фрагмент кода.
+
+````markdown
+```plantuml
+@startuml
+Alice -> Bob: Hello Bob
+Bob --> Alice: Hi!
+@enduml
+```
+````
+
+Вы можете использовать плагин для преобразования в картинку схемы.
+
+```python
+from markdown_pdf import MarkdownPdf, Section
+from markdown_pdf.pligins import Plugin
+
+plugins = {
+  # использовать умолчания
+  Plugin.Plantuml: None
+  # или задать адрес вашего сервера
+  # Plugin.Plantuml: {'url': 'http://www.plantuml.com/plantuml/img/'}
+}
+
+pdf = MarkdownPdf(plugins=plugins)
+pdf.add_section(Section(markdown_text_with_plantuml_code))
+pdf.save("plantuml.pdf")
+```
+
+В полученном pdf файле код `plantuml` будет заменен на следующую картинку.
+
+![plantuml.png](fixture/plantuml.png)
+
+## mermaid
+
+Плагин для кода `mermaid` заменяет код на картинку, создаваемую при помощи внешнего сервера (по умолчанию `https://mermaid.ink`).
+
+В вашем `markdown` документе имеется следующий фрагмент кода.
+
+````markdown
+```mermaid
+stateDiagram-v2
+    [*] --> Still
+    Still --> [*]
+
+    Still --> Moving
+    Moving --> Still
+    Moving --> Crash
+    Crash --> [*]
+```
+````
+
+Вы можете использовать плагин для преобразования этого кода в картинку.
+
+```python
+from markdown_pdf import MarkdownPdf, Section
+from markdown_pdf.pligins import Plugin
+
+plugins = {
+  # использовать умолчания
+  Plugin.Mermaid: None
+  # или задать адрес вашего сервера
+  # Plugin.Mermaid: {'url': 'https://mermaid.ink/img/'}
+}
+
+pdf = MarkdownPdf(plugins=plugins)
+pdf.add_section(Section(markdown_text_with_mermaid_code))
+pdf.save("mermaid.pdf")
+```
+
+В полученном pdf файле код `mermaid` будет заменен на следующую картинку.
+
+![mermaid.png](fixture/mermaid.png)