Skip to content

Commit

Permalink
Adding note about 404 pages.
Browse files Browse the repository at this point in the history
Updated NFSN docs with my experiences.
  • Loading branch information
Robpol86 committed Aug 25, 2016
1 parent 97077a9 commit 9c427e5
Showing 1 changed file with 35 additions and 0 deletions.
35 changes: 35 additions & 0 deletions docs/nfsn.rst
Original file line number Diff line number Diff line change
Expand Up @@ -178,3 +178,38 @@ and remove the previous sphinx-versioning line.
After committing you should see Travis CI push HTML files to NFSN and your site should be up and running with your
documentation.

Robots and 404 Pages
====================

Since you're using NFSN to host your docs you'll probably want to setup a 404 page as well as a ``robots.txt``. A
robots.txt is pretty easy: just place it in your **docs** directory (next to conf.py) and add
``html_extra_path = ['robots.txt']`` to your conf.py.

A 404 page is slightly more involved. First add a 404.rst in your docs directory. Then create a
**docs/_templates/layout.html** file and add this to it:

.. code-block:: jinja
{% if pagename == '404' and scv_is_root %}
{% set metatags = '<base href="/">\n ' + metatags %}
{% endif %}
.. note::

The base href thing fixes the relative URLs problem on 404 errors in subdirectories. If users go to
`http://scversioning.nfshost.com/unknown/index.html` Apache will serve the /404.html file contents without having
browsers change the current directory path. This causes browsers to resolve relative URLs (and CSS files) in
404.html to for example `http://scversioning.nfshost.com/unknown/_static/css/theme.css` which itself is a 404.
``<base href="/">`` fixes this so browsers resolve all relative URLs/links/etc to
`http://scversioning.nfshost.com/_static/css/theme.css`.

Next you need to tell NFSN to give browsers 404.html on an HTTP 404 error. Add an ``.htaccess`` file in your docs
directory and put ``ErrorDocument 404 /404.html`` in it.

Finally to tie it all together add this to your **conf.py**:

.. code-block:: python
templates_path = ['_templates']
html_extra_path = ['.htaccess', 'robots.txt']

0 comments on commit 9c427e5

Please sign in to comment.