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 initto 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
<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
@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
@shelftells the Runestone software where your book belongs in the categories on the Runestone library page.
pretext deployon the command line, or simply
git pushthe changes described above to GitHub if you are comfortable with git. The
deploycommand 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
publishedversion of your book. When you open an issue (in the next step) inquire about how to specify this in your
project.ptxfile. 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/newto 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.