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
, runpretext 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 yourproject.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 namedpublication/runestone.ptx
. 2) You should change your<output-dir>
to point topublished/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 simplygit push
the changes described above to GitHub if you are comfortable with git. Thedeploy
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 apublished
version of your book. When you open an issue (in the next step) inquire about how to specify this in yourproject.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