GithubHelp home page GithubHelp logo

isolveit / mkdocs-pdf-generate Goto Github PK

View Code? Open in Web Editor NEW
6.0 6.0 0.0 11.56 MB

An MkDocs plugin to generate individual PDF files from content pages.

Home Page: https://isolveit.github.io/mkdocs-pdf-generate/

License: MIT License

Python 81.97% CSS 16.70% Jinja 1.32%
markdown mkdocs mkdocs-material mkdocs-plugin pdf pdf-document-processor pdf-generation weasyprint

mkdocs-pdf-generate's Introduction

Hi GitHub User ๐Ÿ‘‹:man:๐Ÿ–ฅ๏ธ,

I'm Randy but you can call me i SOLve IT. I am a ๐Ÿ Python Developer with experience in working with Sphinx & MkDocs and building extensions for both Sphinx & MkDocs. I also develop web apps and RESTful API using Flask.

Right now, I'm happy working in the Docs-as-Code ecosystem.

I am passionate about learning new things and sharing ideas with both engineers and non-engineers. Also, I write about my opinions and knowledge on my ๐Ÿ”— blog site.

Currently, I am learning about Embedded systems using Raspberry Pi 4 Module with Python and Mobile app development with Flutter. Also, I am fascinated by drone technology and aspire to become a professional drone pilot.

I appreciate a company environment that supports workers, creates room for innovation, and encourages teamwork.

๐Ÿ“ซ To know more about the work I do, feel free to go through my GitHub repositories and also visit my Twitter ๐Ÿฆ or LinkedIn ๐Ÿ”— profiles.

Visitor count ๐Ÿงฎ

โฌ†๏ธ Added recently ๐Ÿ˜บ

mkdocs-pdf-generate's People

Contributors

isolveit avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar

mkdocs-pdf-generate's Issues

site_url is required, causing a stacktrace

I tried adding this plugin in a minimal example, but the code requires a site_url to be set:

_css_escape(re.sub(r"http://|https://", "", options.site_url)),

This now causes a unfriendly stacktrace:

ERROR    -  Error building page 'index.md': Error converting index.md to PDF: expected string or bytes-like object
Traceback (most recent call last):
  File "/home/user/.cache/pypoetry/virtualenvs/myrepo-6tCRwMjb-py3.10/lib/python3.10/site-packages/mkdocs_pdf_generate/plugin.py", line 150, in on_post_page
    self.renderer.write_pdf(
  File "/home/user/.cache/pypoetry/virtualenvs/myrepo-6tCRwMjb-py3.10/lib/python3.10/site-packages/mkdocs_pdf_generate/renderer.py", line 37, in write_pdf
    self.render_doc(content, base_url, pdf_metadata=pdf_metadata).write_pdf(
  File "/home/user/.cache/pypoetry/virtualenvs/myrepo-6tCRwMjb-py3.10/lib/python3.10/site-packages/mkdocs_pdf_generate/renderer.py", line 46, in render_doc
    style_tags: list[Tag] = style_for_print(self._options, pdf_metadata)
  File "/home/user/.cache/pypoetry/virtualenvs/myrepo-6tCRwMjb-py3.10/lib/python3.10/site-packages/mkdocs_pdf_generate/styles/__init__.py", line 52, in style_for_print
    _css_escape(re.sub(r"http://|https://", "", options.site_url)),
  File "/usr/lib/python3.10/re.py", line 209, in sub
    return _compile(pattern, flags).sub(repl, string, count)
TypeError: expected string or bytes-like object

I'm very new to mkdocs and this pdf-generate plugin, so I don't feel confident to suggest a good fix. I guess a fallback value is needed in case this property isn't set.

I now have set the site_url property and it builds fine again.

Combined pdf option

My main use-case is to generate a single pdf from the mkdocs documentation. This plugin is the best I found available at the moment, but lacks the combined pdf feature, although there is some commented out code available in the repo. It is however not instrumented to be run.

It seem to be coming from https://github.com/zhaoterryy/mkdocs-pdf-export-plugin/tree/master/mkdocs_pdf_export_plugin but the overall structure is different to the point where a 1:1 copy doesn't make sense. I started adding this feature but I quickly ran into the structural changes that warrant a different approach for a combined pdf.

What is the roadmap for supporting a combined pdf generation?

Furthermore, I have noticed two shortcomings from other plugins I would like to raise here as well:

Relative heading levels according to the nav: section inm the mkdocs.yml

When you have pages lower in the hierarchy starting with a header one, the resulting pdf outline doesn't match the tree in the nav section. I can think of two solutions:

  • demote heading levels for nested pages.
  • explicitly set the pdf outline to match that of the nav

Mermaid.js handling

Mermaid.js is has become one of the default code-based diagramming solutions.
It is also supported in mkdocs-material https://squidfunk.github.io/mkdocs-material/reference/diagrams/
However when rendering the pdf, the diagram is shown just as a code block:

afbeelding

I found this Pandoc filter to handle mermaid cases. Something like that might be interesting, of course implemented differently. Perhaps even as a separate plugin, not sure how that would work with mkdocs. https://github.com/raghur/mermaid-filter Original thread of implementing mermaid.js in material theme for reference: squidfunk/mkdocs-material#693

PDF Override Option

There are some documents that may be released with incomplete sections. For these documents, it is possible that the PDF is not released for the new revision just yet.

For these cases, it is useful to have an override option that will let you specify a relative path or a complete URL and if the PDF exists, the PDF button will be pointing to it instead of a newly built PDF.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.