So, we are currently working on a new version of the Stacks project website. If you have any suggestions for the new website, please get in touch: you can email me, or use the issue tracker for the website on GitHub. The project is called Gerby, as a silly reference to the Stacks project. It consists of several parts, and this blog post explains you how to use one of them: the Gerby renderer in plasTeX.

Also, if you want to set up your own Stacks project-like website, the new system will be much more compatible with other texts, so you can contact me if you are interested in doing this.

Right now we are still quite far from replacing the current website. But the most complicated part is in some sense over: we can

  • split the TeX file according to all the different tags
  • convert this to HTML in a much more robust way than before

We are now using plasTeX for this, a Python library which was originally written for converting the SAS documentation written in TeX to various formats. Below you can find the instructions for running the Gerby renderer on the Stacks project, and see for yourself how it works.

Instructions on running the Gerby renderer

To get plasTeX up and running:

  1. run git clone https://github.com/pbelmans/plastex.git

  2. run git checkout gerby in the repository

  3. run pip3 install --editable . in the repository directory (or your preferred method of installing Python scripts)

To run it on the Stacks project (this part will become easier in the future)

  1. run git clone https://github.com/stacks/stacks-project.git

  2. run make tags/tmp/book.tex in the repository (this creates a single buildable TeX file of the Stacks project)

  3. change the preamble of tags/tmp/book.tex:

    • the document class should be book, i.e. replace the first few lines by 
      \documentclass{book}
    • add 
      \usepackage{amsmath}
    • remove (this is optional) 
      \newenvironment{reference}{\comment}{\endcomment}
\newenvironment{slogan}{\comment}{\endcomment}
\newenvironment{history}{\comment}{\endcomment}
    • add 
      \def\reversemarginpar{}
\def\marginnote#1{}
\def\hypertarget#1#2{}
      at the end of the preamble

    You will have to redo this each time you run make tags/tmp/book.tex!

  4. run ln -s tags/tags tags/tmp/tags in the repository

You should now be ready to run plasTeX: run plastex --renderer=Gerby book.tex in the directory tags/tmp.

Now you can go for a walk. After 30 minutes (give or take, depending on your computer) you will have a directory tags/tmp/book containing several tens of thousands small files containing HTML. Congratulations! Next time I'll tell you what to do with these.

The only thing you need to run this on your own project is a tags file. This is a text file linking tags to labels. You must create one yourself, because the system only generates files for tags.

Remarks

Be aware of the following:

  • remove the package amsthm, it makes plasTeX very confused

That's it for now, I'll add remarks as I think of them.