Documentation updates for version 1.28.0

Author: jamie-lemon

docs/about-feature-matrix.rst

@@ -55,6 +55,10 @@
           :width: 0
           :height: 0
 
+.. image:: images/icons/icon-md.svg
+          :width: 0
+          :height: 0
+
 .. raw:: html
 
 
@@ -181,6 +185,11 @@
             background-size: 40px 40px;
         }
 
+        #feature-matrix .icon.md {
+            background: url("_images/icon-md.svg") 0 0 transparent no-repeat;
+            background-size: 40px 40px;
+        }
+
     </style>
 
 
@@ -207,6 +216,7 @@
                 <span class="icon cbz"><cite>CBZ</cite></span>
                 <span class="icon svg"><cite>SVG</cite></span>
                 <span class="icon txt"><cite>TXT</cite></span>
+                <span class="icon md"><cite>MD</cite></span>
                 <span class="icon image"><cite id="transFM3">Image</cite></span>
                 <hr/>
                 <span class="icon docx"><cite>DOCX</cite></span>

docs/about.rst

@@ -97,7 +97,7 @@ The following table illustrates what features the products offer:
      - PyMuPDF Pro
      - PyMuPDF4LLM
    * - **Input Documents**
-     - `PDF`, `XPS`, `EPUB`, `CBZ`, `MOBI`, `FB2`, `SVG`, `TXT`, Images (*standard document types*)
+     - `PDF`, `XPS`, `EPUB`, `CBZ`, `MOBI`, `FB2`, `SVG`, `TXT`, `MD`, Images (*standard document types*)
      - *as PyMuPDF* and:
        `DOC`/`DOCX`, `XLS`/`XLSX`, `PPT`/`PPTX`, `HWP`/`HWPX`
      - *as PyMuPDF*

docs/app3.rst

@@ -421,6 +421,60 @@ Typical document page sizes are **ISO A4** and **Letter**. A **Letter** page has
 
 
 
+
+.. _CSS_Support:
+
+CSS Support
+--------------------------------------------
+
+For now, only a subset of CSS properties are supported.
+
+The underlying C library MuPDF supports a subset of HTML4 and CSS2. The primary goal of the HTML/CSS support is to serve as a popular and convenient way to style text — not to faithfully reproduce websites in PDF.
+
+What Works
+~~~~~~~~~~~~~
+
+The following list shows the supported properties and their possible values. The list is not exhaustive, but it gives an idea of what to expect.
+
+Text styling
+""""""""""""""
+
+
+``color``
+``font-family``
+``font-size``
+``font-weight`` (bold)
+``font-style`` (italic)
+``text-align``
+``line-height``
+``letter-spacing`` 
+``text-decoration`` (underline etc.)
+
+Box model (basic)
+""""""""""""""""""""""""""""
+
+``margin``
+``padding``
+``border`` 
+``background-color`` (applies to the text's occupied sub-rectangle, not the full box)
+
+Fonts
+""""""""""""""
+
+``@font-face`` for loading custom fonts via an Archive
+Standard variants (regular, bold, italic, bold-italic) via ``font-weight`` and ``font-style``
+
+Layout
+""""""""""""""
+
+Only relative layout is available. No ``position: absolute``, no ``flexbox``, no ``grid``, no ``float``, no ``clear``. The layout is basically a flow layout, where the text is laid out in lines and paragraphs, and the lines are laid out in blocks.
+
+
+What Doesn't Work
+~~~~~~~~~~~~~~~~~~~~~~~~~~ 
+
+Modern CSS (CSS3+): no ``flexbox``, ``grid``, ``custom properties`` (--vars), ``calc()``, ``transitions``, ``animations``, ``position: absolute`` / ``fixed``, ``float``, ``clear`` and so on.
+
 .. rubric:: Footnotes
 
 .. [#f1] MuPDF supports "deep-copying" objects between PDF documents. To avoid duplicate data in the target, it uses so-called "graftmaps", like a form of scratchpad: for each object to be copied, its :data:`xref` number is looked up in the graftmap. If found, copying is skipped. Otherwise, the new :data:`xref` is recorded and the copy takes place. PyMuPDF makes use of this technique in two places so far: :meth:`Document.insert_pdf` and :meth:`Page.show_pdf_page`. This process is fast and very efficient, because it prevents multiple copies of typically large and frequently referenced data, like images and fonts. However, you may still want to consider using garbage collection (option 4) in any of the following cases:

docs/archive-class.rst

@@ -10,7 +10,7 @@ Archive
 
 This class represents a generalization of file folders and container files like ZIP and TAR archives. Archives allow accessing arbitrary collections of file folders, ZIP / TAR files and single binary data elements as if they all were part of one hierarchical tree of folders.
 
-In PyMuPDF, archives are currently only used by :ref:`Story` objects to specify where to look for fonts, images and other resources.
+In PyMuPDF, archives are currently only used by :ref:`Story` objects and as an :ref:`option when opening files <Full_Options_for_Opening_a_File>` to specify where to look for fonts, images and other resources.
 
 ================================ ===================================================
 **Method / Attribute**           **Short Description**

docs/converting-files.rst

@@ -11,7 +11,7 @@ Converting Files
 Files to PDF
 ~~~~~~~~~~~~~~~~~~
 
-:ref:`Document types supported by PyMuPDF<HowToOpenAFile>` can easily be converted to |PDF| by using the :meth:`Document.convert_to_pdf` method. This method returns a buffer of data which can then be utilized by |PyMuPDF| to create a new |PDF|.
+:ref:`Document types supported by PyMuPDF <HowToOpenAFile>` can easily be converted to |PDF| by using the :meth:`Document.convert_to_pdf` method. This method returns a buffer of data which can then be utilized by |PyMuPDF| to create a new |PDF|.
 
 
 
@@ -20,38 +20,97 @@ Files to PDF
 .. code-block:: python
 
     import pymupdf
-
+    
+    # Convert Markdown to PDF
+    md_doc = pymupdf.open("example.md")
+    pdfdata = md_doc.convert_to_pdf()
+    pdf_doc = pymupdf.open(stream=pdfdata)
+    pdf_doc.save("example.pdf")
+
+    # Convert XPS to PDF
     xps = pymupdf.open("input.xps")
-    pdfbytes = xps.convert_to_pdf()
-    pdf = pymupdf.open("pdf", pdfbytes)
+    pdfdata = xps.convert_to_pdf()
+    pdf = pymupdf.open(stream=pdfdata)
     pdf.save("output.pdf")
 
+.. _Markdown_to_PDF:
 
+Markdown to PDF
+~~~~~~~~~~~~~~~~~
 
-PDF to SVG
-~~~~~~~~~~~~~~~~~~
+As Markdown files are supported input files they can be easily converted to PDF using the :meth:`Document.convert_to_pdf` method.
 
-Technically, as SVG files cannot be multipage, we must export each page as an SVG.
+In the simplest case you can just open the Markdown file and call the method to get a PDF representation of the content. 
 
-To get an SVG representation of a page use the :meth:`Page.get_svg_image` method.
 
-**Example**
+Defining paper size
+"""""""""""""""""""
+
+The default paper size is 400 x 600 :doc:`rect` but you can specify a custom paper size if you wish, to do this just send through the `rect` parameter as required, for example:
 
 .. code-block:: python
 
-    import pymupdf
+    md_doc = pymupdf.open("example.md", rect=pymupdf.paper_rect("A4")) # A4 size
 
-    doc = pymupdf.open("input.pdf")
-    page = doc[0]
 
-    # Convert page to SVG
-    svg_content = page.get_svg_image()
+Defining CSS
+""""""""""""
+
+By default, the Markdown content will be converted to PDF using a default CSS stylesheet. However, you can specify your own CSS stylesheet to customize the appearance of the resulting PDF. To do this, define your `css` and apply it.
+
+For example, to make all ``h1`` headers red (The single ``#`` symbol in Markdown), you could do the following:
+
+.. code-block:: python
+
+    md_doc = pymupdf.open(  # open the Markdown document in A4 size
+        "example.md",
+        rect=pymupdf.paper_rect("A4")
+    )
+     
+    css = "h1 {color:red;}"
+    md_doc.apply_css(css)
+
+    pdf_doc = pymupdf.open(stream=md_doc.convert_to_pdf())
+    pdf_doc.ez_save("red-colored-header.pdf")
+
+.. note::
+
+    The :ref:`support for CSS <CSS_Support>` is currently limited.
+
+
+Defining Fonts
+"""""""""""""""""
+
+Fonts can be defined by using the `archive` parameter to provide a custom :ref:`Archive` containing the font files.
+
+The fonts must exist in an archive which is provided to the `archive` parameter when opening the Markdown file. The CSS can then refer to these fonts by their names as defined in the archive.
+
+For example, assuming you have access to the source files for the "Comic Sans" font for all text, you could do the following:
+
+.. code-block:: python
+
+    # Global CSS instructions to use the "Comic Sans" font for all text. The font files must be provided in the archive.
+    css = """
+    @font-face {font-family: sans-serif; src: url(comic.ttf);}
+    @font-face {font-family: sans-serif; src: url(comicbd.ttf); font-weight: bold;}
+    @font-face {font-family: sans-serif; src: url(comicz.ttf); font-weight: bold; font-style: italic;}
+    @font-face {font-family: sans-serif; src: url(comici.ttf); font-style: italic;}
+    """
+
+    archive = pymupdf.Archive("C:/Windows/Fonts")  # the fonts are here
+    archive.add(".")  # we've stored the archive image in this script's folder
+
+    md_file = "sample.md"
+    md_doc = pymupdf.open(  # open the Markdown document
+        md_file,
+        archive=archive,  # where to look for resources (fonts, images)
+        rect=pymupdf.paper_rect("A4"),  # page dimension ISO A4
+    )
+
+    md_doc.apply_css(css) 
+
 
-    # Save to file
-    with open("output.svg", "w", encoding="utf-8") as f:
-        f.write(svg_content)
 
-    doc.close()
 
 
 PDF to Markdown
@@ -72,6 +131,31 @@ By utlilizing the :doc:`PyMuPDF4LLM API <pymupdf4llm/api>` we are able to conver
     pathlib.Path("4llm-output.md").write_bytes(md_text.encode())
 
 
+PDF to SVG
+~~~~~~~~~~~~~~~~~~
+
+Technically, as SVG files cannot be multipage, we must export each page as an SVG.
+
+To get an SVG representation of a page use the :meth:`Page.get_svg_image` method.
+
+**Example**
+
+.. code-block:: python
+
+    import pymupdf
+
+    doc = pymupdf.open("input.pdf")
+    page = doc[0]
+
+    # Convert page to SVG
+    svg_content = page.get_svg_image()
+
+    # Save to file
+    with open("output.svg", "w", encoding="utf-8") as f:
+        f.write(svg_content)
+
+    doc.close()
+
 PDF to DOCX
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

docs/document.rst

@@ -10,7 +10,7 @@ Document
 
 This class represents a document. It can be constructed from a file or from memory.
 
-There exists the alias *open* for this class, i.e. `pymupdf.Document(...)` and `pymupdf.open(...)` do exactly the same thing.
+There is an alias :meth:`open` for this class, i.e. `pymupdf.Document(...)` and `pymupdf.open(...)` do exactly the same thing.
 
 For details on **embedded files** refer to Appendix 3.
 
@@ -29,6 +29,7 @@ For details on **embedded files** refer to Appendix 3.
 ======================================= ==========================================================
 :meth:`Document.add_layer`              PDF only: make new optional content configuration
 :meth:`Document.add_ocg`                PDF only: add new optional content group
+:meth:`Document.apply_css`              Markdown only: apply CSS stylesheet to Markdown content
 :meth:`Document.authenticate`           gain access to an encrypted document
 :meth:`Document.bake`                   PDF only: make annotations / fields permanent content
 :meth:`Document.can_save_incrementally` check if incremental save is possible
@@ -169,7 +170,7 @@ For details on **embedded files** refer to Appendix 3.
     pair: rect; Document
     pair: fontsize; Document
 
-  .. method:: __init__(self, filename=None, stream=None, *, filetype=None, rect=None, width=0, height=0, fontsize=11)
+  .. method:: __init__(self, filename=None, stream=None, filetype=None, archive=None, rect=None, width=0, height=0, fontsize=11)
 
     Create a ``Document`` object.
 
@@ -183,11 +184,13 @@ For details on **embedded files** refer to Appendix 3.
 
     :arg str filetype: A string specifying the type of document. This is only ever needed when file content inspection fails. Text types like "txt", "html", "xml" etc. cannot be disambiguated by their content. When such files are provided in memory or being provided with the wrong file extension, this parameter **must** be used.
 
-    :arg rect_like rect: a rectangle specifying the desired page size. This parameter is only meaningful for documents with a variable page layout ("reflowable" documents), like e-books or HTML, and ignored otherwise. If specified, it must be a non-empty, finite rectangle with top-left coordinates (0, 0). Together with parameter :data:`fontsize`, each page will be accordingly laid out and hence also determine the number of pages.
+    :arg Archive archive: An optional :ref:`Archive` object to use as a source for resources like fonts and images.
 
-    :arg float width: may used together with ``height`` as an alternative to ``rect`` to specify layout information.
+    :arg rect_like rect: A rectangle specifying the desired page size. This parameter is only meaningful for documents with a variable page layout ("reflowable" documents), like e-books, MD or HTML, and ignored otherwise. If specified, it must be a non-empty, finite rectangle with top-left coordinates (0, 0). Together with parameter :data:`fontsize`, each page will be accordingly laid out and hence also determine the number of pages.
 
-    :arg float height: may used together with ``width`` as an alternative to ``rect`` to specify layout information.
+    :arg float width: May be used together with ``height`` as an alternative to ``rect`` to specify layout information.
+ 
+    :arg float height: May be used together with ``width`` as an alternative to ``rect`` to specify layout information.
 
     :arg float fontsize: the default :data:`fontsize` for reflowable document types. This parameter is ignored if none of the parameters ``rect`` or ``width`` and ``height`` are specified. Will be used to calculate the page layout.
 
@@ -201,24 +204,29 @@ For details on **embedded files** refer to Appendix 3.
 
       In case of problems you can see more detail in the internal messages store: `print(pymupdf.TOOLS.mupdf_warnings())` (which will be emptied by this call, but you can also prevent this -- consult :meth:`Tools.mupdf_warnings`).
 
-    Overview of possible forms, note: `open` is a synonym of `Document`::
 
-        >>> # from a file
-        >>> doc = pymupdf.open("some.xps")
-        >>> # handle wrong extension
-        >>> doc = pymupdf.open("some.file", filetype="xps")  # assert expected type
-        >>> doc = pymupdf.open("some.file", filetype="txt")  # treat as plain text
-        >>>
-        >>> # from memory
-        >>> doc = pymupdf.open(stream=mem_area)  # works for any supported type
-        >>> doc = pymupdf.open(stream=unknown-type, filetype="txt")  # treat as plain text
-        >>>
-        >>> # new empty PDF
-        >>> doc = pymupdf.open()
-        >>> doc = pymupdf.open(None)
-        >>> doc = pymupdf.open("")
+    Overview of possible forms, note: :meth:`open` is a synonym of :meth:`Document`::
+
+        # from a file
+        doc = pymupdf.open("some.xps")
+        # handle wrong extension
+        doc = pymupdf.open("some.file", filetype="xps")  # assert expected type
+        doc = pymupdf.open("some.file", filetype="txt")  # treat as plain text
+        
+        # from memory
+        doc = pymupdf.open(stream=mem_area)  # works for any supported type
+        doc = pymupdf.open(stream=unknown_type, filetype="txt")  # treat as plain text
+        
+        # new empty PDF
+        doc = pymupdf.open()
+        doc = pymupdf.open(None)
+        doc = pymupdf.open("")
 
-    .. note:: Raster images with a wrong (but supported) file extension **are no problem**. MuPDF will determine the correct image type when file **content** is actually accessed and will process it without complaint.
+    .. note:: 
+        
+        Raster images with a wrong (but supported) file extension **are no problem**. MuPDF will determine the correct image type when file **content** is actually accessed and will process it without complaint.
+
+        See :ref:`supported file types <Supported_File_Types>` for more information.
 
     The Document class can be also be used as a **context manager**. Exiting the content manager will close the document automatically.
 
@@ -2030,6 +2038,20 @@ For details on **embedded files** refer to Appendix 3.
     This is a normal PDF document with no usage restrictions whatsoever. If it is not being changed in any way, it can be used together with its journal to undo / redo operations or continue updating.
 
 
+  .. method:: apply_css(css, append=True)
+
+    * New in v1.28.0
+
+    Apply CSS styles to the document. This is a global operation, which means that the styles will be applied to all pages and all elements of the document. The CSS syntax is the same as for HTML documents, but only a subset of CSS properties is supported.
+
+    :arg str css: a string containing the CSS styles to be applied.
+    :arg bool append: whether to append the new styles to existing ones (if any) or to replace them.
+
+    .. note:: This method is primarily intended for use with :ref:`Markdown documents <Markdown_to_PDF>`.
+
+
+
+
   .. attribute:: outline
 
     Contains the first :ref:`Outline` entry of the document (or `None`). Can be used as a starting point to walk through all outline items. Accessing this property for encrypted, not authenticated documents will raise an *AttributeError*.