6

For most of my project's documentation I prefer a standard sphinx layout. However for the landing page I would prefer to use custom HTML/CSS/JS without any of the layout, TOC, or sidebars of the normal sphinx site. Is there a way to include a raw HTML standalone page in a sphinx-generated website in a way that completely disregards the normal layout of the rest of the site?

As a counter example I know that I can include raw HTML bits into a page using the following (see also this question)

.. raw:: html
   :file: myfile-html

However this just embeds a file within the normal layout. I would like to have a completely standalone HTML page.

MRocklin
  • 55,641
  • 23
  • 163
  • 235
  • You can change the base `index` page to something else in `conf.py` (the `master_doc` setting), and manually include your own raw `index.html` file in build. – jiminy_crist Feb 20 '18 at 16:43
  • 4
    To clarify a bit, you can include raw html pages in the output with the `html_extra_path` setting in `conf.py` http://www.sphinx-doc.org/en/master/config.html#confval-html_extra_path. In your case you'd change `master_doc='docs'` (or a different path) to not generate an `index.html` page, and add `html_extra_path=['index.html']` to include your raw landing page file. – jiminy_crist Feb 20 '18 at 17:09

1 Answers1

5

I just ran into this problem myself, and the way I solved it was to simply include the html file in my source/_static folder, then refer to it with a relative link.

So if source/_static/my_standalone.htm is the path where I have my non-generated HTML file, and the .rst file where I want to type my link is at source/otherfolder/index.rst, I write it like this in my rst:

Link to my non-Sphinx HTML file
===============================

To get to my standalone, non-generated HTML file, 
just `click here <../_static/my_standalone.html>`_ now!
Bill M.
  • 1,388
  • 1
  • 8
  • 16