Search code examples
htmlpdfmarkdowngithub-pagesmkdocs

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

I have a private repository with some pdf files among others. The content is however, made publicly available using MkDocs (material) and github-pages. I want to embed these locally available pdf files on the website (created with MkDocs). So far I have tried this:

# Method-1
<object data="/path/to/file.pdf" type="application/pdf">
    <embed src="/path/to/file.pdf" type="application/pdf" />
</object>

# Method-2
<a href="/path/to/file.pdf" class="image fit"><i class="fas fa-file-pdf"></i></a>

The /path/to/file.pdf, when shared from Google Drive (made publicly available), works. But, it does not work when I try to show the files kept within the docs folder in my github repository.

How can I show them from the repository itself (without having to copy and share the files from GDrive)?

For github pages:

  • only the contents of the docs folder are pushed to the gh-pages branch and then GitHub Pages publishes these contents as the website.

Related Material

Solution

  • Solution

    The main challenge in making the pdf file available on the published site is creating a link that is not broken and actually accesses the file from the repository.

    Mkdocs comes with a lot of extensions, that enhance the functionality of the framework. You need to use pymdownx.pathconverter to address this issue.

    Example

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

    enter image description here

    Here are the pieces you need to work with.

    A. Install PyMdown Extension

    Along with Other must haves...

    pip install \
    mkdocs \
    mkdocs-material \
    mkdocs-material-extensions \
    pymdown-extensions

    B. Update mkdocs.yml

    Add the following to mkdocs.yml

    # 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'

    A note to the reader: You can also use a relative path with pymdownx.pathconverter. For details, please see the documentation. However, for brevity, in case you end up using relative path, this is what your need to do:

    1. Set absolute: false in the extension settings for pymdownx.pathconverter.

    2. Use relative path (this should take into account your URL path hierarchy). For instance, if you embed a pdf-file docs/artifacts/file.pdf in a markdown file docs/howto/embedding_pdf.md and the link to the markdown file looks like http://localhost:8000/demo_mkdocs_project/howto/embedding-a-pdf-file (please see the following sections for more context), then the relative path to the file while embedding it, would look like:

    "../../artifacts/file.pdf"

    C. Embed PDF file from the repository

    Here we will assume the pdf file is located at: docs/artifacts/file.pdf and the docs folder is located at the root of the repository. In the following code block I embed a pdf in the file docs/howto/embedding_pdf.md.

    <!--- file: docs/howto/embedding_pdf.md --->
{% with pdf_file = "artifacts/file.pdf" %}

{% set solid_filepdf = '<i class="fas fa-file-pdf"></i>' %}
{% set empty_filepdf = '<i class="far fa-file-pdf"></i>' %}

## Example: Embedding a PDF file

<object data="{{ pdf_file }}" type="application/pdf">
    <embed src="{{ pdf_file }}" type="application/pdf" />
</object>

## Example: Creating a link to a PDF file

<a href="{{ pdf_file }}" class="image fit">{{ solid_filepdf }}</a>

{% endwith %}

    D. Add a link to the page in mkdocs.yml

    This will create a top-level link HowTo and then under that another link Embedding a PDF file.

    # file: mkdocs.yml

nav:
  - Home: index.md
  - HowTo:
    - Embedding a PDF file: howto/embedding_pdf.md

    These four steps essentially make the pdf file available both on your local server (localhost:8000) and on github pages (in case you are publishing there). The link to the file would then resemble this:

    • Local server: http://localhost:8000/demo_mkdocs_project/artifacts/file.pdf

    • GitHub Pages: http://githubid.github.io/demo_mkdocs_project/artifacts/file.pdf

    Note:

    I assumed the

    • Git userid: githubid
    • repository name: demo_mkdocs_project

    References

    1. PyMdown Extensions Documentation - PathConverter