.. _`Github pages`: http://pages.github.com/
.. _`Github maven plugins`: https://github.com/github/maven-plugins
.. _`Jekyll`: https://github.com/mojombo/jekyll/

Frequently Asked Questions
==========================

When I put documentation generated by Sphinx on `Github pages`_, then it looks all mangled and broken. Why is that ?

    Github pages by default uses a system called `Jekyll`_ to generate the documentation. This usually
    works just fine with already generated content. However Jekyll regards directory names beginning
    with an underscore to be special and won't make them available on the website. Sphinx however uses
    directories like `_source` and `_static` for the site which means it won't work properly. Fortunately
    the fix is easy. In your `gh-pages` branch of your project on github, simply create a file called `.nojekyll`
    in the root folder. Once you pushed that file, Jekyll will be turned off for the site and the
    documentation should look as intended.
    If you are using the `Github maven plugins`_ to deploy your site, then you can tell the `site-maven-plugin` to
    automatically maintain the `.nojekyll` file by adding::

        <noJekyll>true</noJekyll>

    to the configuration of the `site-maven-plugin` plugin (since version 0.5 of the plugin).