How to serve extra static files?

[twpayne]

Firstly, thank you for a really nice tool :)

Is it possible to add extra static files to be served by mkdocs?

In my specific case, I have an install script that I'd like to serve from the relative URL /get on my site. /get could either be the contents of the script itself or trigger a redirect to a different location.

I've tried the following:

---

Creating a file called get with the contents I want in my docs directory and adding the following to my config:

theme:
  static_templates:
    - get

With this, I get the following error:

$ mkdocs serve
INFO     -  Building documentation...
INFO     -  Cleaning site directory
WARNING  -  Template skipped: 'get' not found in theme directories.
INFO     -  Documentation built in 0.58 seconds
INFO     -  [19:39:48] Serving on http://127.0.0.1:8000/

Note that the contents of get is a shell script, not a Markdown file.

---

Installing the redirects plugin and adding the following to my config:

plugins:
- redirects:
    redirect_maps:
      get: https://github.com/twpayne/chezmoi/raw/master/assets/scripts/install.sh

With this I get the following error:

$ mkdocs serve
INFO     -  Building documentation...
INFO     -  Cleaning site directory
WARNING  -  redirects plugin: 'get' is not a valid markdown file!
[Errno 20] Not a directory: '/tmp/mkdocs_9xk7w1to/get/index.html'

---

I also looked for a way to add this static file to the gh-pages branch before deploying to GitHub with mkdocs gh-deploy, but there seems to be no hook for this.

Any help appreciated!

[squidfunk]

mkdocs serve is only meant for previewing. If you want to serve files with specific content types and as downloads, you'll need a proper reverse proxy or file server. I'm not sure if GitHub Pages will set the right headers so *.sh will be a download. The redirects plugin is probably not a good choice for this, as its purpose is to redirect links to HTML files.

[twpayne]

Thanks for the fast response :)

The content type and headers don't actually matter, only the content does.

It sounds like serving static files is not possible with mkdocs at the moment. Looking at the source code for the redirects plugin it looks like it should be possible to write a plugin to do this.

[twpayne]

I eventually achieved this by using the mkdocs-simple-hooks plugin.

I put the following in mkdocs.yml:

- mkdocs-simple-hooks:
    hooks:
      on_post_build: "docs.hooks:copy_get"

And the following in docs/hooks.py:

import os
import shutil

def copy_get(config, **kwargs):
    site_dir = config['site_dir']
    shutil.copy('assets/scripts/install.sh', os.path.join(site_dir, 'get'))