Mkdocs: Customizing readthedocs theme does not work out of the box

[jbick]

I followed the instructions to customize a theme*. The mkdocs theme works, readthedocs leads to the following error:

Traceback (most recent call last):
  File "d:\software\python27\lib\runpy.py", line 162, in _run_module_as_main
    "__main__", fname, loader, pkg_name)
  File "d:\software\python27\lib\runpy.py", line 72, in _run_code
    exec code in run_globals
  File "D:\software\python27\Scripts\mkdocs.exe\__main__.py", line 9, in <module>
  File "d:\software\python27\lib\site-packages\click\core.py", line 716, in __call__
    return self.main(*args, **kwargs)
  File "d:\software\python27\lib\site-packages\click\core.py", line 696, in main
    rv = self.invoke(ctx)
  File "d:\software\python27\lib\site-packages\click\core.py", line 1060, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "d:\software\python27\lib\site-packages\click\core.py", line 889, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "d:\software\python27\lib\site-packages\click\core.py", line 534, in invoke
    return callback(*args, **kwargs)
  File "d:\software\python27\lib\site-packages\mkdocs\__main__.py", line 115, in serve_command
    livereload=livereload,
  File "d:\software\python27\lib\site-packages\mkdocs\commands\serve.py", line 78, in serve
    config = builder()
  File "d:\software\python27\lib\site-packages\mkdocs\commands\serve.py", line 74, in builder
    build(config, live_server=True, clean_site_dir=True)
  File "d:\software\python27\lib\site-packages\mkdocs\commands\build.py", line 289, in build
    build_pages(config)
  File "d:\software\python27\lib\site-packages\mkdocs\commands\build.py", line 235, in build_pages
    if not build_template('search.html', env, config, site_navigation):
  File "d:\software\python27\lib\site-packages\mkdocs\commands\build.py", line 148, in build_template
    output_content = template.render(context)
  File "d:\software\python27\lib\site-packages\jinja2\environment.py", line 989, in render
    return self.environment.handle_exception(exc_info, True)
  File "d:\software\python27\lib\site-packages\jinja2\environment.py", line 754, in handle_exception
    reraise(exc_type, exc_value, tb)
  File "D:\projekte\jira\docs\custom_readthedocs\base.html", line 30, in <module>
    var mkdocs_page_name = {{ page_title|tojson|safe }};
jinja2.exceptions.TemplateAssertionError: no filter named 'tojson'

I tried to install flask with pip but that doesn't seem to be enough. Am I missing something obvious?

• Note: Many links inside the mkdocs docs link to http://www.mkdocs.org/user-guide/styling-your-docs/#custom-themes which does not exist.

[waylan]

The error is pretty clear. Just look at the last 3 lines:

File "D:\projekte\jira\docs\custom_readthedocs\base.html", line 30, in <module>
    var mkdocs_page_name = {{ page_title|tojson|safe }};
jinja2.exceptions.TemplateAssertionError: no filter named 'tojson'

On line 30 of D:\projekte\jira\docs\custom_readthedocs\base.html you are using the tojson filter and that filter does not exist. I just checked and the Jinja template engine does not provide such a filter by default. And I don't see where MkDocs uses or defines such a filter. Therefore you would need to define and import the filter yourself.

[jbick]

Yeah, but I did not change the code: https://github.com/mkdocs/mkdocs/blob/master/mkdocs/themes/readthedocs/base.html#L30

Thats why I wrote "out of the box".

[d0ugal]

It is defined here and enabled here.

I assume it isn't working for you because you took the theme from git master, but you are running a released version of MkDocs. The filter is a new addition.

[johnennewdeeson]

Find out your mkdocs version with

mkdocs --version

Then checkout that tag release for mkdocs and copy the readthedocs theme out of that.