Skip to main content

The PreTeXt Guide

Robert A. Beezer, David Farmer, Alex Jordan, Mitchel T. Keller

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.8.) Then perform the usual conversion to online HTML, as described in Chapter 29 but also be sure to specify the 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.
While this HTML may be manually deployed to any Runestone server, authors who wish to publish their work on the Runestone Academy 1  server have a few more requirements.
  • Your project must be managed using the CLI (Section 5.2). If you didn't create it using pretext new, run pretext init to get started upgrading. You'll also need to make it available to the public via GitHub (instructions below).
  • 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 a new file, 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.
  • Copy the usual publication file you use for your html-format build target and name it as publication/runestone.ptx (or whatever you chose in the previous step). Edit this file so your <html> element matches the example above.
  • 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.
  • 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 haven't 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.).
  • Runestone servers are able to host both a draft and a published version of your book. When you open an issue (in the next step) inquire about how to specify this in your project.ptx file. Then let us know, so you are the only person to have to ask. Thanks.
  • 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.
Runestone.Academy
<Prev^TopNext>