How to embed a local pdf file in mkdocs generated website on github-pages?

[sugatoray]

The Objective

I needed to embed pdf files in the site generated with mkdocs. The catch is the pdf files are maintained in private repository on GitHub, under the docs folder. So, my initial work around was to upload these files on GDrive and then share them from there. But, this makes maintainability harder as you go along and also makes the whole process rather clunky.

Stackoverflow Question

So, I asked a question on stackoverflow: How to embed a local pdf file in mkdocs generated website on github-pages?

But, did not get any response that would solve the problem.

Solution

🚀 Finally, I was able to figure it out by using pymdownx.pathconverter to make these links to the pdf files accessible, even for the private repository.

🔥 I posted a rather detailed solution on stackoverflow.

I hope this turns useful for others using MkDocs and MkDocs Material. However, if you have any other example/suggestion, I am all ears! 👍

Example

I have blurred out the contents from the screenshot. But you can see how the embedded pdf file looks like.

Reference

• pymdownx.pathconverter: https://facelessuser.github.io/pymdown-extensions/extensions/pathconverter/

[shanthisagar-dhanya-kumar-db-zz]

Does this solution work only for github?
I tried with hosted bitbucket, but the page renders empty

[sugatoray]

I have not tested this on bitbucket (only on GitHub). So, please share your findings if you are able to make it work.

[sugatoray]

You might want to try with changing any path mentioned with an extra ./, . or / in front of it (such as the path of the pdf file).

Also consider playing with the absolute vs. relative path options here.

# Strategy: Use an absolute path
markdown_extensions:
  - pymdownx.pathconverter:
      base_path: 'YOUR_REPO_NAME' # default: ''
      relative_path: '' # default ''
      absolute: true # default: false
      tags: 'a script img link object embed'