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 thegh-pages
branch and then GitHub Pages publishes these contents as the website.
CodePudding user response:
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.
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:
Set
absolute: false
in the extension settings forpymdownx.pathconverter
.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 filedocs/howto/embedding_pdf.md
and the link to the markdown file looks likehttp://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