Search code examples
pythonmarkdownmkdocsmkdocs-material

mkdocs: how to attach a downloadable file

I have a mkdocs project that resembles the following:

project
├─mkdocs.yml
├─docs
│ ├─home.md
│ ├─chapter1.md
│
├─static
  ├─file.ext
  ├─image.png

I am trying to find a way to "attach" file1.ext to the build, for instance as a link in chapter1.md.

Any suggestions how to achieve that? Detail: I want the file to be downloadable on click.

Solution

  • In mkdocs, to get the file to be downloadable on click using markdown, first you need to add this to your mkdocs.yml file :

    markdown_extensions:
  - attr_list

    and then in your chapter1.md you can add download attribute to your link ... like so :

    [file.ext](../static/file.ext){:download}

    Heck you can even name the downloaded file:

    [file.ext](../static/file.ext){:download="awesome-file"}

    Explanation

    MkDocs converts Markdown to HTML using Python-Markdown which offers a flexible extension mechanism, which makes it possible to change and/or extend the behavior of the parser without having to edit the actual source files.

    The markdown_extensions in mkdocs.yml setting specifies the Python-Markdown extensions for MkDocs. adding attr_list entry point enables the Python-Markdown attribute lists extension, which adds support for HTML-style attributes using curly brackets {} and a CSS-like syntax.

    example:

    let's say we want to open a link in new tab, we can achieve this like so :

    [Google](https://www.google.com){:target="_blank"}