Clickable hyperlinks. (#51)

Author: vb64

README.md

@@ -17,6 +17,7 @@ When creating a PDF file you can:
 - Tune the necessary elements using your CSS code
 - 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.
 
 The module utilizes the functions of two great libraries.
 
@@ -47,24 +48,38 @@ from markdown_pdf import Section
 pdf.add_section(Section("# Title\n", toc=False))
 ```
 
-Add a second section. In the pdf file it starts on a new page.
+Add a second section with external and internal hyperlinks.
+In the pdf file it starts on a new page.
+
+```python
+text = """# Section with links
+
+- [External link](https://github.com/vb64/markdown-pdf)
+- [Internal link to Head1](#head1)
+- [Internal link to Head3](#head3)
+"""
+
+pdf.add_section(Section(text))
+```
+
+Add a third section.
 The title is centered using CSS, included in the table of contents of the pdf file, and an image from the file `img/python.png` is embedded on the page.
 
 ```python
 pdf.add_section(
-  Section("# Head1\n\n![python](img/python.png)\n\nbody\n"),
+  Section("# <a name='head1'></a>Head1\n\n![python](img/python.png)\n\nbody\n"),
   user_css="h1 {text-align:center;}"
 )
 ```
 
-Add a third section. Two headings of different levels from this section are included in the TOC of the pdf file.
+Add a next section. Two headings of different levels from this section are included in the TOC of the pdf file.
 The section has landscape orientation of A4 pages.
 
 ```python
-pdf.add_section(Section("## Head2\n\n### Head3\n\n", paper_size="A4-L"))
+pdf.add_section(Section("## Head2\n\n### <a id='head3'></a>Head3\n\n", paper_size="A4-L"))
 ```
 
-Add a fourth section with a table.
+Add a section with a table.
 
 ```python
 

README_ru.md

@@ -11,6 +11,7 @@
 - Оформлять нужные элементы при помощи вашего CSS кода
 - Использовать разные размеры страниц внутри одного pdf
 - Создавать таблицы в `markdown`
+- Использовать кликабельные гиперссылки. Спасибо [@thongtmtrust](https://github.com/thongtmtrust) за идеи и сотрудничество!
 
 Модуль использует функции двух замечательных библиотек.
 
@@ -41,24 +42,38 @@ from markdown_pdf import Section
 pdf.add_section(Section("# Title\n", toc=False))
 ```
 
-Добавляем вторую секцию. В pdf-файле она начинается с новой страницы.
+Добавляем вторую секцию с внешними и внутренними гипер-ссылками.
+В pdf-файле она начинается с новой страницы.
+
+```python
+text = """# Section with links
+
+- [External link](https://github.com/vb64/markdown-pdf)
+- [Internal link to Head1](#head1)
+- [Internal link to Head3](#head3)
+"""
+
+pdf.add_section(Section(text))
+```
+
+Добавляем третью секцию.
 Заголовок центрируется при помощи CSS, включается в оглавление pdf-файла и на страницу встраивается изображение из файла `img/python.png`.
 
 ```python
 pdf.add_section(
-  Section("# Head1\n\n![python](img/python.png)\n\nbody\n"),
+  Section("# <a name='head1'>Head1\n\n![python](img/python.png)\n\nbody\n"),
   user_css="h1 {text-align:center;}"
 )
 ```
 
-Добавляем третью секцию. Два заголовка разного уровня из этой секции включаются в оглавление pdf-файла.
+Добавляем следующую секцию. Два заголовка разного уровня из этой секции включаются в оглавление pdf-файла.
 Секция имеет альбомную ориентацию страниц A4.
 
 ```python
-pdf.add_section(Section("## Head2\n\n### Head3\n\n", paper_size="A4-L"))
+pdf.add_section(Section("## Head2\n\n### <a id='head3'></a>Head3\n\n", paper_size="A4-L"))
 ```
 
-Добавляем четвертую секцию с таблицей.
+Добавляем секцию с таблицей.
 
 ```python
 

examples/markdown_pdf.pdf

@@ -0,0 +1,30 @@
+# Module markdown-pdf
+
+[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/vb64/markdown-pdf/pep257.yml?label=Pep257&style=plastic&branch=main)](https://github.com/vb64/markdown-pdf/actions?query=workflow%3Apep257)
+[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/vb64/markdown-pdf/py3.yml?label=Python%203.8-3.13&style=plastic&branch=main)](https://github.com/vb64/markdown-pdf/actions?query=workflow%3Apy3)
+[![Codacy Badge](https://app.codacy.com/project/badge/Grade/27b53043bff34f07bfb79ee1672b7ba0)](https://app.codacy.com/gh/vb64/markdown-pdf/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
+[![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.
+
+When creating a PDF file you can:
+
+- Use `UTF-8` encoded text in `markdown` in any language
+- Embed images used in `markdown`
+- Break text into pages in the desired order
+- Create a TableOfContents (bookmarks) from markdown headings
+- Tune the necessary elements using your CSS code
+- Use different page sizes within single pdf
+- Create tables in `markdown`
+
+The module utilizes the functions of two great libraries.
+
+- [markdown-it-py](https://github.com/executablebooks/markdown-it-py) to convert `markdown` to `html`.
+- [PyMuPDF](https://github.com/pymupdf/PyMuPDF) to convert `html` to `pdf`.
+
+## Installation
+
+```bash
+pip install markdown-pdf
+```

examples/markdown_pdf_ru.pdf

@@ -1,3 +1,5 @@
++ Clickable hyperlinks.
+
 07.03.2025 ver.1.4
 ------------------
 

fixture/hrefs.md

@@ -51,11 +51,15 @@ def __init__(self, toc_level: int = 6, mode: str = 'commonmark'):
 
         self.out_file = io.BytesIO()
         self.writer = fitz.DocumentWriter(self.out_file)
-        self.page = 0
+        self.page_num = 0
+        self.hrefs = []
 
     @staticmethod
     def _recorder(elpos):
         """Call function invoked during story.place() for making a TOC."""
+        elpos.page_num = elpos.pdfile.page_num
+        elpos.pdfile.hrefs.append(elpos)
+
         if not elpos.open_close & 1:  # only consider "open" items
             return
         if not elpos.toc:
@@ -65,7 +69,7 @@ def _recorder(elpos):
             elpos.pdfile.toc.append((
                 elpos.heading,
                 elpos.text,
-                elpos.pdfile.page,
+                elpos.pdfile.page_num,
                 elpos.rect[1],  # top of written rectangle (use for TOC)
             ))
 
@@ -77,7 +81,7 @@ def add_section(self, section: Section, user_css: typing.Optional[str] = None) -
         story = fitz.Story(html=html, archive=section.root, user_css=user_css)
         more = 1
         while more:  # loop outputting the story
-            self.page += 1
+            self.page_num += 1
             device = self.writer.begin_page(rect)
             more, _ = story.place(where)  # layout into allowed rectangle
             story.element_positions(self._recorder, {"toc": section.toc, "pdfile": self})
@@ -89,7 +93,8 @@ def add_section(self, section: Section, user_css: typing.Optional[str] = None) -
     def save(self, file_name: typing.Union[str, pathlib.Path]) -> None:
         """Save pdf to file."""
         self.writer.close()
-        doc = fitz.open("pdf", self.out_file)
+        self.out_file.seek(0)
+        doc = fitz.Story.add_pdf_links(self.out_file, self.hrefs)
         doc.set_metadata(self.meta)
         if self.toc_level > 0:
             doc.set_toc(self.toc)

history.txt

@@ -22,12 +22,12 @@ def test_with_toc(self):
 
         pdf = MarkdownPdf(toc_level=2)
         pdf.add_section(Section("# Title\n", toc=False))
+        pdf.add_section(Section(TABLE_TEXT))
         pdf.add_section(
           Section("# Head1\n\n![python](img/python.png)\n\nbody\n"),
           user_css="h1 {text-align:center;}"
         )
         pdf.add_section(Section("## Head2\n\n### Head3\n\n"))
-        pdf.add_section(Section(TABLE_TEXT))
         pdf.save(self.build("with_toc.pdf"))
 
     def test_no_toc(self):
@@ -70,3 +70,13 @@ def test_empty_head(self):
         pdf = MarkdownPdf(toc_level=2)
         pdf.add_section(Section("# "))
         pdf.save(self.build("empty-head.pdf"))
+
+    def test_hrefs(self):
+        """Convert hrefs content to pdf."""
+        from markdown_pdf import Section, MarkdownPdf
+
+        pdf = MarkdownPdf()
+        pdf.add_section(
+          Section(open(self.fixture("hrefs.md"), "rt", encoding='utf-8').read())
+        )
+        pdf.save(self.build("hrefs.pdf"))

markdown_pdf/__init__.py

@@ -0,0 +1,44 @@
+"""Readme example code.
+
+make test T=test_readme.py
+"""
+from . import TestBase
+
+
+class TestReadme(TestBase):
+    """Latex content."""
+
+    def test_en(self):
+        """Test README.md example code."""
+        from markdown_pdf import Section, MarkdownPdf
+
+        pdf = MarkdownPdf(toc_level=2)
+        pdf.add_section(Section("# Title\n", toc=False))
+
+        text = """# Section with links
+
+- [External link](https://github.com/vb64/markdown-pdf)
+- [Internal link to Head1](#head1)
+- [Internal link to Head3](#head3)
+"""
+        pdf.add_section(Section(text))
+
+        pdf.add_section(
+          Section("# <a name='head1'></a>Head1\n\n![python](img/python.png)\n\nbody\n"),
+          user_css="h1 {text-align:center;}"
+        )
+        pdf.add_section(Section("## Head2\n\n### <a id='head3'></a>Head3\n\n", paper_size="A4-L"))
+        text = """# Section with Table
+
+|TableHeader1|TableHeader2|
+|--|--|
+|Text1|Text2|
+|ListCell|<ul><li>FirstBullet</li><li>SecondBullet</li></ul>|
+"""
+        css = "table, th, td {border: 1px solid black;}"
+        pdf.add_section(Section(text), user_css=css)
+
+        pdf.meta["title"] = "User Guide"
+        pdf.meta["author"] = "Vitaly Bogomolov"
+
+        pdf.save(self.build("readme.pdf"))