Skip to main content

The PreTeXt Guide

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

Section 44.4 Online (HTML) Options

These options affect the base conversion to web pages (online, HTML). Many, but not all, will affect subsequent conversions based on HTML, such as a conversion to EPUB or Jupyter notebooks. See Chapter 29 for a more general overview of this conversion, including options that will eventually migrate here.

Subsection 44.4.1 HTML Analytics

The
/publication/html/analytics
element can have the following attributes:
  • @google-gst: a Google global site tag, which is an ID you get from Google. Do not copy the identification numbers from another project—be sure to obtain your own for your project.
  • @statcounter-project, @statcounter-security: ID numbers you get from StatCounter. Do not copy the identification numbers from another project—be sure to obtain your own for your project.
Setting these attributes to non-empty strings is the signal to add the relevant code to each of the pages of your HTML output. See Section 29.7 for more.

Subsection 44.4.2 HTML Base URL

The
/publication/html/baseurl/@href
attribute may be given as a complete URL for the top-level of where HTML output is hosted. Of course, this may be different for different publishers. The value is a directory, and so should end with a slash (path separator). See Subsection 29.1.5 for reasons why you might want to specify this.

Subsection 44.4.3 HTML Embedded Calculator

The
/publication/html/calculator
element has the following attribute:
  • @model: used to control which calculator is available on every page. Possible values are:
    • geogebra-classic
    • geogebra-graphing
    • geogebra-geometry
    • geogebra-3d
    • none
The default is none. See Subsection 29.1.2 for more.

Subsection 44.4.4 HTML Favicon

The
/publication/html/
element has the following attribute:
  • @favicon: used to control how icon files for a favicon are embedded into each HTML page:
    • none
    • simple
The default is none. See Subsection 29.1.3 for more, including an explanation of what a favicon is.

Subsection 44.4.5 HTML WeBWorK Dynamism

The
/publication/html/webwork
element has the following attributes, each of which can have a value of static or dynamic:
  • @inline, default value: dynamic
  • @divisional, default value: static
  • @reading, default value: static
  • @worksheet, default value: static
  • @project, default value: dynamic
The attribute names suggest the type of exercise or project-like that will be affected. See Subsection 38.4.2 for more details and the rationale for the defaults.

Subsection 44.4.6 HTML ActiveCode Programming Window

The
/publication/html/calculator
element has the following attribute:
  • @activecode: used to control if an ActiveCode window is available on every page, and if so, which language it undestands. Possible values are:
    • python (Python)
    • javascript (JavaScript)
    • html (HTML)
    • sql (SQL)
    • c (C, Runestone server only)
    • cpp (C++, Runestone server only)
    • java (Java, Runestone server only)
    • python3 (Python 3, Runestone server only)
    • octave (Octave, Runestone server only)
    • none
For a build hosted at a Runestone server, python is the default. For an HTML build hosted elsewhere, none is the default. See Subsection 29.1.4 for more.

Subsection 44.4.7 HTML Index Page

The
/publication/html/index-page
element can have the following attribute:
  • @ref: the @xml:id of a division which will be a complete page at whatever level the document is chunked (broken into smaller pages).
An index.html page will be created which redirects immediately to this page. Many webservers will serve this page when a URL stops with the enclosing directory. So the Table of Contents (<book>, <article>) or the <frontmatter> are common choices. See Subsection 29.1.1 for more.

Subsection 44.4.8 HTML Knowlization

In a conversion to HTML a wide variety of content can be “born” in a knowl. Publisher switches are specified via multiple attributes of a single
/publication/html/knowl
element, with values of yes (do use a knowl) or no (do not use a knowl, present content normally). For example,
<knowl remark="yes"/>
would make every “remark-like” element occur as a knowl where the content is first introduced. Note that these are distinctly different than cross-reference knowls. For more detail see Section 29.2.
This table gives the various attribute names, the default value, and an indication of the elements affected. Note that some items are automatically born knowled (e.g. footnotes) and so there is no option to control that behavior. Also, items such as <figure>, when included in a <sidebyside> are not influenced by the relevant option and are not born knowled. There are four flavors of <exercise> and so four options. A <hint>, <answer>, or <solution> is automatically knowled as a plot-spoiler where the author is expecting the reader to do something. In contrast, an “example-like” is expository, so the knowlization is configurable.
Table 44.4.1. Knowlization options
Attribute Default Element(s)
theorem no <theorem>, <lemma>, …
proof yes <proof>
definition no <definition>
example yes <example>, <problem>, …
example-solution yes <hint>, <answer>, <solution>
project no <project>, <activity>, …
task no <task>
remark no <remark>, <note>, …
objectives no <objectives>
outcomes no <outcomes>
figure no <figure>
table no <table>
listing no <listing>
list no <list>
exercise-inline yes within narrative
exercise-divisional no inside <exercises> division
exercise-worksheet no inside <worksheet> division
exercise-readingquestion no inside <readingquestions> division

Subsection 44.4.9 HTML Tabbed viewer

The
/publication/html/exercises
element can have a @tabbed-tasks attribute. The value is a space-separated, or comma-separated, list of types of <exercise> or PROJECT-LIKE. The values in this list come specify up to four of the five possible types of exercises: divisional, inline, reading, project. Note that exercises inside a <worksheet> are explicity ineligible. See Section 3.9 for careful descriptions of these types.

Subsection 44.4.10 HTML Platforms

The
/publication/html
element can have an attribute @platform with values:
  • web: the default, meant for self-hosting with no server configuration, features, or assumptions
  • runestone: output meant for hosting on a Runestone server (Chapter 32)
Here platform refers to the server where the HTML output will eventually be hosted. The effect is to create minor variations in the output to take advantage of extra features of the indicated platform.

Subsection 44.4.11 HTML Style (Theme)

The
/publication/html/css
element can have a @theme to specify the theme used to style the pages. See Section 29.6 for examples of what different themes look like. Depending on the theme chosen, there may be other attributes that can be set. See List 44.4.2 below for details.
The “legacy” stylesheets are still available. Any publication file that references html/css/@style will use the corresponding legacy style sheet (default, crc, wide, oscar-levin) as well as the colors selected for it. However, the full range of configuration is no longer available. If your publisher file mixes legacy style parts in an unexpected way (toc="crc" but sidebar="wide") you will get one or the other complete style.
New themes other than “default-modern” require a build step involving node.js. If you are using the CLI, installing node will be handled for you. If you are using the pretext/pretext script, you will need to manually install node (see Appendix F) and then, one time, run npm install in the script/cssbuilder directory. Once node is installed, the necessary build script will automatically be invoked when you build a document.
To rapidly test out different themes and options while using the CLI (see Subsection 5.2.3) you can use pretext build --theme to rebuild the theme without a full book rebuild. If you are using the pretext script (see Chapter 47) you can use the flag -c theme. Note that doing this assumes the HTML needed for the different themes is the same. This should generally be the case, but if you encounter odd rendering issues you should do a full rebuild.
List 44.4.2. Theme attribute options
default-modern
The following attributes can be set on CSS to modify the appearance of default-modern:
  • @palette controls the colors used. Options include: "blue-red", "blue-green", "green-blue", "greens", and "blues".
  • @primary-color override the primary color set by the palette. This, and all other color attributes, can be in CSS color format (hex, rbg, hsletc.).
  • @secondary-color override the secondary color set by the palette.
  • @provide-dark-mode can be set to "no" to disable dark mode on the theme. This may be desirable if the work has significant elements that do not render correctly with a dark background and you are not able to modify them to do so.
  • @primary-color-dark override the primary color used in dark mode.
tacoma, greeley
The following attributes can be set on CSS to modify the appearance of tacoma and greely. They function in the same way as the corresponding attributes for default-modern.
  • @primary-color
  • @primary-color-dark
  • @provide-dark-mode
salem, denver
The following attributes can be set on CSS to modify the appearance of salem and denver.
  • @palette controls the colors used. Options include: "bold", "bold2", "primaries", "primaries2", "ice-fire", "earth-sea", "leaves", and "slate".
  • @color-main override the primary color set by the palette.
  • @color-do override the color used for elements that ask the reader to do something (e.g. an exercise).
  • @color-fact override the color used for elements that present a fact (e.g. a theorem).
  • @color-meta override the color used for elements that provide meta information to the reader (e.g. goals, remarks).
  • @provide-dark-mode - see default-modern.
  • @primary-color-dark - see default-modern.
Finally, if you wish to do development on a custom theme using SCSS, you can set /publication/html/css/@theme to "custom". If you do so, you need to also set @entry-point to be the path to an SCSS file that will be used to build the theme. This path should be relative to the xml file that is your document root.

Subsection 44.4.12 HTML Search

The
/publication/html/search
element can have the following attributes:
  • @variant: a string specifying how search queries are handled. Possible values are textbook, reference, default and none. For historical reasons, using the value default is synonymous with using textbook, so it is not necessary. If you do not specify this entry, then that is equivalent to setting the value to textbook. This is search provided natively.
  • @google-cx: a Google cx number, gained from configuring search for a site. Setting this attribute to a non-empty string is the signal to add the relevant code for a search box in the masthead.
Note that if you elect both native search and Google search the two search boxes will overlay each other and one will not be usable. See Section 29.8 and Section 29.9 (respectively) for more.

Subsection 44.4.13 HTML Video Embedding

The
/publication/html/video
element can have the following attribute:
  • @privacy: allowed values are yes or no.
Setting this to yes (the default) prevents certain tracking cookies from being used. Currently only supported for videos from YouTube. See Subsection 29.1.6 for more.

Subsection 44.4.14 Short Answer Responses

The
/publication/html
element can have an attribute @short-answer-responses with values:
  • graded: the default, only show an area for responses when they can be graded or scored (such as when hosted on Runestone, Chapter 32).
  • always: include an editable response area, even if it cannot be submitted for feedback.
See Subsection 4.12.9 for details.

Subsection 44.4.16 HTML Feedback Button

The
/publication/html/feedback
element requires an @href attribute that is a complete URL. The content of the element is optional, and will provide alternate text for the button. This alternate text should have no markup—just text. See Subsection 29.1.8 for explanations, details, and a caveat.

Subsection 44.4.17 HTML Navigation Options

The
/publication/html/navigation
element can have the following attributes:
  • @logic with values linear (default) and tree.
  • @upbutton with values yes (default) and no.
See Subsection 29.1.9 for explanations and details.

Subsection 44.4.18 HTML Table of Contents Options

The
/publication/html/tableofcontents
element can have the following attributes:
  • @focused with values no (default) and yes. Enabling a focused TOC makes the TOC expandable/collapsible and initialliy hides TOC items not on the path to the active webpage.
  • @preexpanded-levels with values 1-6 (0 is the default). This value controls how many levels from the root of the TOC are initially expanded outside of the path to the current page. Either 0 or 1 will result in the root level of the TOC being expanded (it is on the path to the active page and thus always is expanded). 2 will result in the first two levels of the TOC being visible (e.g. parts and chapters or chapters and sections). 3 would result in three initially visible levels (e.g. parts/chapters/sections), etc...
See Subsection 29.1.9 for explanations and details.

Subsection 44.4.19 xref Options

The
/publication/html/cross-references
element can have the following attributes:
  • @knowled with values maximum (default), never and cross-page. maximum will render xref’s to structural elements as HTML links and xref’s to smaller elements as knowls. never forces all xref’s to be rendered as traditional HTML links. cross-page bases the rendering decision on if the xref and its target are on the same page. If so, the xref is always rendered as an HTML link. If the link and target are on different pages, the behavior is the same as maximum
See Section 29.2 for explanations and details.
PrevTopNext