Publishing to Runestone Academy

Section 32.2 Publishing to Runestone Academy

The usual PreTeXt HTML output (Chapter 29) only needs minor modifications to run profitably on a Runestone server. You accomplish this via a publication file (Section 26.1). The absolute simplest publication file to accomplish this is

<publication>
  <html>
    <platform host="runestone"/>
  </html>
</publication>

(See Subsection 44.4.9.) Then perform the usual steps for a conversion to online HTML, as described in Chapter 29 but also be sure to specify the correct publication file. The output should appear like a usual PreTeXt document, but will now include a new menu on each page. This has options which allow a reader or instructor to interact with the Runestone server, once hosted there. So it will not look entirely right when you view it locally, since you are not a Runestone server, but you should see subtle differences.

While this HTML may be manually deployed to any Runestone server, authors who wish to publish their work on the Runestone Academy ¹ server have a few more requirements.

Hoasting on Runestone assumes certain details conform to how a project is organized for use by the CLI (Section 5.2). So if you are managing your project with the CLI already, you are in good shape. If you did not create your project using pretext new, run pretext init to get started upgrading. You will also need to make your project available to the public via GitHub (instructions below).
Copy the publication file you usually use for your html-format build target and name it as publication/runestone.ptx (or something similar thst makes sens in your project). Edit this file so your <html> element matches the example at the start of this section.
You should create a new <target name="runestone"></target> in your project.ptx. The contents of this tag will differ from your usual html-format build target in the following ways. 1) You should change your <publication> to point to the new file you just created, perhaps named publication/runestone.ptx. 2) You should change your <output-dir> to point to published/document-id, where <document-id> is defined in your <docinfo>. Note Runestone’s preferred practice for the <document-id> is to have a simple lowercase string with no dashes or other special characters. This value is visible to readers who want to register for your course on Runestone outside of any formal setting.
Update the <docinfo> section of your book so that it includes a <blurb> with a @shelf. The blurb should not contain any additional markup, just a simple string, that describes your book. Think of something like what you would read on a book jacket. It might even also be used automatically in the future for exactly that: a blurb on the back cover of a hardback book. So keep it simple—straight ASCII text, nothing fancy. The @shelf tells the Runestone software where your book belongs in the categories on the Runestone library page. Look at the Runestone library page to see what values are in use and copy an existing one exactly including capitalization. If you think a new shelf is necessary in the library, please seek advice on what to use.
Use pretext deploy on the command line, or simply git push the changes described above to GitHub if you are comfortable with git. The deploy command will walk you through setup if you have not deployed your project to github before. You do not have to enable GitHub Pages unless you want to. (GitHub Pages does not have the features of a Runestone server, and will not render a build for the Runestone target properly. You can host your regular html-format build on GitHub.)
With Runestone Academy and the author interface you can see a draft of your book on
```
staging.runestoneacademy.org
```
When you are ready you can make a published version of your book available with the click of a button. We can set up access to the author interface when you open an issue (in the next step) requesting that your book be added to Runestone Academy.
Log into GitHub and open an issue at github.com/RunestoneInteractive/RunestoneServer/issues/new to request that your project be added to Runestone Academy. Be sure to provide the URL of your GitHub repository (e.g. https://github.com/UserName/repo-name/). Runestone Academy administrators will communicate with you via GitHub to complete this process.

Prev Top Next