Sphinx

Sphinx is the static site generator I use for this website. It can convert pages written in reStructuredText into HTML. This is convenient since reStructuredText is faster to write than HTML, plus you only have to focus on the body text of each page. Everything else is automatically generated for you, so your site’s layout and navigation will be consistent across every page.

Download

Sphinx is available on many package managers, including Chocolatey for Windows and the Python package manager, pip. If you haven’t used these before, see how to install Python packages.

Setup

Create a folder you want your website’s files in, open a terminal in that folder, and run the command sphinx-quickstart. This will ask you a few questions about how you want your website set up, and use those to generate some starter files for you.

The table of contents

One of the files it will generate is index.rst, which will be the homepage for your website. You can write whatever you’d like to appear on the homepage, and this is also where you’ll set up your table of contents, the primary navigation for your site. If you want a copy of your TOC on the page, you’ll write it where you want it to appear; otherwise I find it convenient to put it at the bottom.

index.rst
==============
Homepage title
==============

This is a welcome message. Hello!

.. toctree::
  :hidden:
  :caption: Pages on my site
  :maxdepth: 3

  page1
  page2

With this setup:

  • The TOC will have a heading that says “Pages on my site”. If you don’t want a heading, you can remove the :caption: line.

  • The TOC will be visible in the sidebar, but not on the homepage itself. Remove the :hidden: option if you want a copy of the TOC on the homepage.

  • The TOC will provide links to 3 levels of depth within each page–the title, subheadings, and sub-sub-headings. Change the number as you like, or remove the option entirely to show links to every heading regardless of depth.

  • page1.rst and page2.rst are files in the same folder as index.rst. If page2.rst was in a folder called morestuff, it could be listed as morestuff/page2.

You can have multiple tables of contents if you want to organize your pages by topic. If you want to include every file in a folder, you can do so by listing folder_name/* in the TOC.

Building the HTML pages

From a terminal in the folder your index.rst is in, run make html. On Windows, you may need to use .\make.bat html. This will read all of your .rst files and convert them into HTML, notifying you of any errors. When it’s done, it will tell you where the files are, probably _build/html. If you go into that folder and open the HTML files in your browser, you can see if your site looks how you want!

Theming

Besides index.rst, another file that was generated when you ran the setup script is conf.py. The html_theme option can be changed to whichever of the built-in themes you’d like to use as a base. To add your own CSS, you can create a file called custom.css in the _static folder; any styles you add there will be used on top of your chosen theme.