Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Portable html: the css and javascript parts #2429

Open
wants to merge 4 commits into
base: master
Choose a base branch
from
Open

Portable html: the css and javascript parts #2429

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
c80c2a7
Add portable-html publication variable
oscarlevin Mar 3, 2025
d9601f0
Schema: Fix publication schema for platform
oscarlevin Mar 3, 2025
2bbb37f
Guide: add documentation for `portable` publication variable
oscarlevin Mar 3, 2025
df092dc
HTML: implement portable html builds using CDN for css and js
oscarlevin Mar 3, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 19 additions & 2 deletions doc/guide/publisher/publication-file.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -626,16 +626,33 @@
<subsection xml:id="online-platform-options">
<title>HTML Platforms</title>
<idx><h>platform</h><h>HTML</h></idx>
<idx><h>host</h><h>HTML</h></idx>
<idx>online platforms</idx>

<p>The<cd>
<cline>/publication/html</cline>
</cd>element can have an attribute <attr>platform</attr> with values:<ul>
<cline>/publication/html/platform</cline>
</cd>element can have an attribute <attr>host</attr> with values:<ul>
<li><c>web</c>: the default, meant for self-hosting with no server configuration, features, or assumptions</li>
<li><c>runestone</c>: output meant for hosting on a Runestone server (<xref ref="runestone"/>)</li>
</ul>Here <term>platform</term> refers to the server where the <init>HTML</init> 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.</p>
</subsection>

<subsection xml:id="online-portable-options">
<title>Portable HTML</title>
<idx><h>platform</h><h>HTML</h></idx>
<idx><h>portable</h><h>HTML</h></idx>
<idx><h>portable html</h></idx>

<p>To limit the number of files and directories created by the HTML conversion,
you can set the
<cd>
<cline>/publication/html/platform/@portable</cline>
</cd>
attribute to the value <c>"yes"</c>.
This will result in the HTML using hosted CSS and Javascript files, rather than including them adjacent to the rest of your output.
This is especially useful in conjunction with setting the <xref ref="common-chunking-options">chunking variable</xref> to 0 to get a single html file.</p>
</subsection>

<subsection xml:id="online-style-options">
<title>HTML Style (Theme)</title>
<idx><h>style</h><h>HTML</h></idx>
Expand Down
16 changes: 9 additions & 7 deletions pretext/pretext.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3858,9 +3858,10 @@ def html(xml, pub_file, stringparams, xmlid_root, file_format, extra_xsl, out_fi
# names for scratch directories
tmp_dir = get_temporary_directory()

# interrogate Runestone server (or debugging switches) and populate
# NB: stringparams is augmented with Runestone Services information
_place_runestone_services(tmp_dir, stringparams, ext_rs_methods)
if get_publisher_variable(xml, pub_file, stringparams, 'portable-html') != "yes":
# interrogate Runestone server (or debugging switches) and populate
# NB: stringparams is augmented with Runestone Services information
_place_runestone_services(tmp_dir, stringparams, ext_rs_methods)

# support publisher file, and subtree argument
if pub_file:
Expand All @@ -3877,11 +3878,12 @@ def html(xml, pub_file, stringparams, xmlid_root, file_format, extra_xsl, out_fi
# consulted during the XSL run and so need to be placed beforehand
copy_managed_directories(tmp_dir, external_abs=external_abs, generated_abs=generated_abs)

# place JS in scratch directory
copy_html_js(tmp_dir)
if get_publisher_variable(xml, pub_file, stringparams, 'portable-html') != "yes":
# place JS in scratch directory
copy_html_js(tmp_dir)

# build or copy theme
build_or_copy_theme(xml, pub_file, stringparams, tmp_dir)
# build or copy theme
build_or_copy_theme(xml, pub_file, stringparams, tmp_dir)

# Write output into temporary directory
log.info("converting {} to HTML in {}".format(xml, tmp_dir))
Expand Down
25 changes: 23 additions & 2 deletions schema/publication-schema.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -315,10 +315,26 @@
<code>
Html =
element html {
attribute platform { "web" | "runestone" }?,
attribute favicon { "none" | "simple" }?,
attribute short-answer-responses { "graded" | "always" }?,
(Analytics? &amp; Baseurl? &amp; Calculator? &amp; WebworkDynamism? &amp; Indexpage? &amp; Knowls? &amp; Exercises? &amp; Css? &amp; Search? &amp; Video? &amp; Asymptote? &amp; Feedback? &amp; NavigationHTML? &amp; Tableofcontents? &amp; Crossreferences?)
(
Analytics? &amp;
Asymptote? &amp;
Baseurl? &amp;
Calculator? &amp;
Css? &amp;
Crossreferences?
Exercises? &amp;
Feedback? &amp;
Indexpage? &amp;
Knowls? &amp;
NavigationHTML? &amp;
Platform? &amp;
Search? &amp;
Tableofcontents? &amp;
Video? &amp;
WebworkDynamism? &amp;
)
}

Analytics =
Expand Down Expand Up @@ -397,6 +413,11 @@
attribute logic { "linear" | "tree" }?,
attribute upbutton { "yes" | "no" }?
}
Platform =
element platform {
attribute host { "web" | "runestone" }
attribute portable { "yes" | "no" }
}
Search =
element search {
attribute variant { "textbook" | "reference" | "none" }?,
Expand Down
33 changes: 29 additions & 4 deletions xsl/pretext-html.xsl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -110,9 +110,34 @@ along with MathBook XML. If not, see <http://www.gnu.org/licenses/>.
<!-- So the name says "dir", but effectively it is "location". -->
<!-- But this is not the intent, nor supported, and thus can -->
<!-- change without warning. -->
<xsl:variable name="html.css.dir" select="'_static/pretext/css'"/>
<xsl:variable name="html.js.dir" select="'_static/pretext/js'"/>
<xsl:variable name="html.jslib.dir" select="'_static/pretext/js/lib'"/>
<xsl:variable name="html.css.dir" select="concat($cdn-prefix, '_static/pretext/css')"/>
<xsl:variable name="html.js.dir" select="concat($cdn-prefix, '_static/pretext/js')"/>
<xsl:variable name="html.jslib.dir" select="concat($cdn-prefix, '_static/pretext/js/lib')"/>

<!-- Add a prefix for the cdn, which is empty unless the portable html variable is true -->
<xsl:param name="cli.version" select="'latest'"/>
<xsl:variable name="cdn-prefix">
<xsl:if test="$b-portable-html">
<xsl:text>https://cdn.jsdelivr.net/gh/PreTeXtBook/html-static@</xsl:text>
<xsl:value-of select="$cli.version"/>
<xsl:text>/dist/</xsl:text>
</xsl:if>
</xsl:variable>

<!-- The css file name is usually "theme.css", but if portable html is selected, -->
<!-- then we use a minified version and need to give the full theme name. -->
<xsl:variable name="html-css-theme-file">
<xsl:choose>
<xsl:when test="$b-portable-html">
<xsl:text>theme-</xsl:text>
<xsl:value-of select="$html-theme-name"/>
<xsl:text>.min.css</xsl:text>
</xsl:when>
<xsl:otherwise>
<xsl:text>theme.css</xsl:text>
</xsl:otherwise>
</xsl:choose>
</xsl:variable>

<!-- Annotation -->
<xsl:param name="html.annotation" select="''" />
Expand Down Expand Up @@ -13068,7 +13093,7 @@ TODO:
<!-- CSS header -->
<xsl:template name="css">
<xsl:if test="not($b-debug-react)">
<link href="{$html.css.dir}/theme.css" rel="stylesheet" type="text/css"/>
<link href="{$html.css.dir}/{$html-css-theme-file}" rel="stylesheet" type="text/css"/>
</xsl:if>
<!-- Temporary until css handling overhaul by ascholer complete -->
<link href="{$html.css.dir}/ol-markers.css" rel="stylesheet" type="text/css"/>
Expand Down
2 changes: 2 additions & 0 deletions xsl/pretext-runestone.xsl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -225,6 +225,7 @@ along with PreTeXt. If not, see <http://www.gnu.org/licenses/>.
<xsl:for-each select="$rs-js-tokens">
<script>
<xsl:attribute name="src">
<xsl:value-of select="$cdn-prefix"/>
<xsl:text>_static/</xsl:text>
<xsl:value-of select="."/>
</xsl:attribute>
Expand All @@ -233,6 +234,7 @@ along with PreTeXt. If not, see <http://www.gnu.org/licenses/>.
<xsl:for-each select="$rs-css-tokens">
<link rel="stylesheet" type="text/css">
<xsl:attribute name="href">
<xsl:value-of select="$cdn-prefix"/>
<xsl:text>_static/</xsl:text>
<xsl:value-of select="."/>
</xsl:attribute>
Expand Down
8 changes: 8 additions & 0 deletions xsl/publisher-variables.xsl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2636,6 +2636,13 @@ along with PreTeXt. If not, see <http://www.gnu.org/licenses/>.
<xsl:variable name="b-host-web" select="$host-platform = 'web'"/>
<xsl:variable name="b-host-runestone" select="$host-platform = 'runestone'"/>

<!-- To create a standalone html document with all css and js served by CDN -->
<!-- we can select platform/@portable to "yes" -->
<xsl:variable name="portable-html">
<xsl:apply-templates select="$publisher-attribute-options/html/platform/pi:pub-attribute[@name='portable']" mode="set-pubfile-variable"/>
</xsl:variable>
<xsl:variable name="b-portable-html" select="$portable-html = 'yes'"/>

<!-- -->
<!-- HTML Favicon Specification -->
<!-- -->
Expand Down Expand Up @@ -3191,6 +3198,7 @@ along with PreTeXt. If not, see <http://www.gnu.org/licenses/>.
</video>
<platform>
<pi:pub-attribute name="host" default="web" options="runestone" legacy-options="aim"/>
<pi:pub-attribute name="portable" default="no" options="yes"/>
</platform>
</html>
<epub>
Expand Down
5 changes: 5 additions & 0 deletions xsl/utilities/report-publisher-variables.xsl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -97,6 +97,11 @@ along with MathBook XML. If not, see <http://www.gnu.org/licenses/>.
<xsl:text> </xsl:text>
<xsl:value-of select="$latex-style"/>
<xsl:text>&#xa;</xsl:text>
<!-- 2025-03-03 portable html switch -->
<xsl:text>portable-html</xsl:text>
<xsl:text> </xsl:text>
<xsl:value-of select="$portable-html"/>
<xsl:text>&#xa;</xsl:text>
<!-- -->

<!--
Expand Down