Skip to content

Commit 9c427e5

Browse files
committed
Adding note about 404 pages.
Updated NFSN docs with my experiences.
1 parent 97077a9 commit 9c427e5

File tree

1 file changed

+35
-0
lines changed

1 file changed

+35
-0
lines changed

docs/nfsn.rst

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -178,3 +178,38 @@ and remove the previous sphinx-versioning line.
178178
179179
After committing you should see Travis CI push HTML files to NFSN and your site should be up and running with your
180180
documentation.
181+
182+
Robots and 404 Pages
183+
====================
184+
185+
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
186+
robots.txt is pretty easy: just place it in your **docs** directory (next to conf.py) and add
187+
``html_extra_path = ['robots.txt']`` to your conf.py.
188+
189+
A 404 page is slightly more involved. First add a 404.rst in your docs directory. Then create a
190+
**docs/_templates/layout.html** file and add this to it:
191+
192+
.. code-block:: jinja
193+
194+
{% if pagename == '404' and scv_is_root %}
195+
{% set metatags = '<base href="/">\n ' + metatags %}
196+
{% endif %}
197+
198+
.. note::
199+
200+
The base href thing fixes the relative URLs problem on 404 errors in subdirectories. If users go to
201+
`http://scversioning.nfshost.com/unknown/index.html` Apache will serve the /404.html file contents without having
202+
browsers change the current directory path. This causes browsers to resolve relative URLs (and CSS files) in
203+
404.html to for example `http://scversioning.nfshost.com/unknown/_static/css/theme.css` which itself is a 404.
204+
``<base href="/">`` fixes this so browsers resolve all relative URLs/links/etc to
205+
`http://scversioning.nfshost.com/_static/css/theme.css`.
206+
207+
Next you need to tell NFSN to give browsers 404.html on an HTTP 404 error. Add an ``.htaccess`` file in your docs
208+
directory and put ``ErrorDocument 404 /404.html`` in it.
209+
210+
Finally to tie it all together add this to your **conf.py**:
211+
212+
.. code-block:: python
213+
214+
templates_path = ['_templates']
215+
html_extra_path = ['.htaccess', 'robots.txt']

0 commit comments

Comments
 (0)