Skip to content

Commit dbfb6c4

Browse files
deiningdeining
authored
User guide, LaTeX: typesetting of formulae using standard syntax (II) (#2195)
1 parent 1d49098 commit dbfb6c4

File tree

7 files changed

+272
-116
lines changed

7 files changed

+272
-116
lines changed

‎layouts/_partials/scripts.html‎

Lines changed: 4 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,5 @@
1-
{{ $needKaTeX := or .Site.Params.katex.enable .Params.math .Params.chem -}}
2-
{{ $needmhchem := or .Site.Params.katex.mhchem.enable .Params.chem -}}
3-
{{ if ge hugo.Version "0.93.0" -}}
4-
{{ $needKaTeX = or $needKaTeX (.Page.Store.Get "hasKaTeX") (.Page.Store.Get "hasmhchem") -}}
5-
{{ $needmhchem = or $needmhchem (.Page.Store.Get "hasmhchem") -}}
6-
{{ else -}}
7-
{{ if or $needKaTeX $needmhchem -}}
8-
{{ warnf "Outdated Hugo version %s, consider upgrading to make full use of all theme features" hugo.Version }}
9-
{{ end -}}
10-
{{ end -}}
1+
{{ $needKaTeX := or .Params.math .Site.Params.katex.enable .Params.chem .Site.Params.chem (.Page.Store.Get "hasKaTeX") (.Page.Store.Get "hasmhchem") -}}
2+
{{ $needmhchem := or .Params.chem .Site.Params.katex.mhchem.enable (.Page.Store.Get "hasmhchem") -}}
113

124
{{ if .Site.Params.markmap.enable -}}
135
<style>
@@ -34,27 +26,8 @@
3426
<script src='{{ "js/deflate.js" | relURL }}'></script>
3527
{{ end -}}
3628

37-
{{ if $needKaTeX -}}
38-
{{/* load stylesheet and scripts for KaTeX support */ -}}
39-
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.19/dist/katex.min.css"
40-
integrity="sha512-6a/jH+OTfV56Vs9Mm+Kl7ZsXWJRM2+EV+JDrW7HLHaf4OU2+9eLkHKFbzpSSbfJ5b60m+7/tQAevrzu7NP7Q2g==" crossorigin="anonymous">
41-
{{/* The loading of KaTeX is deferred to speed up page rendering */ -}}
42-
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.19/dist/katex.min.js"
43-
integrity="sha512-FkmlbBiAj8fgfoZ8zJ+bZQCU5pdU55irXmJzFF/mXlSvBr2x/gmyLHaRu5iSpcA5Hw6CMLCCFSjB1GmgtNL2Qg=="
44-
crossorigin="anonymous">
45-
</script>
46-
{{ if $needmhchem -}}
47-
{{/* To add support for displaying chemical equations and physical units, load the mhchem extension: */ -}}
48-
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.19/dist/contrib/mhchem.min.js"
49-
integrity="sha512-Cl4bz7Rt9ppgcBOQa4z96q3UqAzHgBzNDm66u2+lDe0ZJQu0Fgz+6jO57E+IZqzlhGzfNBY++pg7Ue+iopaLrg=="
50-
crossorigin="anonymous">
51-
</script>
52-
{{ end -}}
53-
{{/* To automatically render math in text elements, include the auto-render extension: */ -}}
54-
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.19/dist/contrib/auto-render.min.js"
55-
integrity="sha512-6bKDPShiPRjAcdeO8T6cedaVEi0pavPbzue/G/ZRiwVlurWZOSZ/vI9fr2lhk8IPXK7z51AZac+zBvZzgDJzDQ==" crossorigin="anonymous"
56-
{{ printf "onload='renderMathInElement(%s, %s);'" (( $.Page.Site.Params.katex.html_dom_element | default "document.body" ) | safeJS ) ( printf "%s" ( $.Page.Site.Params.katex.options | jsonify )) | safeHTMLAttr }}>
57-
</script>
29+
{{ if $needKaTeX -}}
30+
{{ partial "scripts/katex.html" (dict "mhchem" $needmhchem) -}}
5831
{{ end -}}
5932

6033
{{ $jsBs := resources.Get "vendor/bootstrap/dist/js/bootstrap.bundle.js" -}}

‎layouts/_partials/scripts/katex.html‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
{{ $version := .Site.Params.katex.version | default "latest" -}}
2+
3+
{{/* load stylesheet and scripts for KaTeX support */ -}}
4+
{{ $katex_css_url := printf "https://cdn.jsdelivr.net/npm/katex@%s/dist/katex%s.css" $version (cond hugo.IsProduction ".min" "") -}}
5+
6+
{{ with try (resources.GetRemote $katex_css_url) -}}
7+
{{ with .Err -}}
8+
{{ errorf "Could not retrieve KaTeX css file from CDN. Reason: %s." . -}}
9+
{{ else with.Value -}}
10+
{{ with resources.Copy (printf "css/katex%s.css" (cond hugo.IsProduction ".min" "")) . }}
11+
{{ $secureCSS := . | resources.Fingerprint "sha512" -}}
12+
<link rel="stylesheet" href="{{- .RelPermalink -}}" integrity="{{- $secureCSS.Data.Integrity -}}" crossorigin="anonymous">
13+
{{ end -}}
14+
{{ end -}}
15+
{{ else -}}
16+
{{ errorf "Invalid KaTeX version %s, could not retrieve this version from CDN." $version -}}
17+
{{ end -}}
18+
19+
{{/* The loading of KaTeX is deferred to speed up page rendering */ -}}
20+
{{ $katex_js_url := printf "https://cdn.jsdelivr.net/npm/katex@%s/dist/katex%s.js" $version (cond hugo.IsProduction ".min" "") -}}
21+
{{ with try (resources.GetRemote $katex_js_url) -}}
22+
{{ with .Err -}}
23+
{{ errorf "Could not retrieve KaTeX script from CDN. Reason: %s." . -}}
24+
{{ else with.Value -}}
25+
{{ with resources.Copy (printf "js/katex%s.js" (cond hugo.IsProduction ".min" "")) . }}
26+
{{ $secureJS := . | resources.Fingerprint "sha512" -}}
27+
<script defer src="{{- .RelPermalink -}}" integrity="{{- $secureJS.Data.Integrity -}}" crossorigin="anonymous" ></script>
28+
{{ end -}}
29+
{{ end -}}
30+
{{ else -}}
31+
{{ errorf "Invalid KaTeX version %s, could not retrieve this version from CDN." $version -}}
32+
{{ end -}}
33+
34+
{{/* Add support for displaying chemical equations and physical units by loading the mhchem extension: */ -}}
35+
{{ if .mhchem -}}
36+
{{ partial "scripts/mhchem.html" (dict "version" $version) -}}
37+
{{ end -}}
38+
39+
{{/* To automatically render math in text elements, include the auto-render extension: */ -}}
40+
41+
{{ $katex_autorender_url := printf "https://cdn.jsdelivr.net/npm/katex@%s/dist/contrib/auto-render%s.js" $version (cond hugo.IsProduction ".min" "") -}}
42+
{{ with try (resources.GetRemote $katex_autorender_url) -}}
43+
{{ with .Err -}}
44+
{{ errorf "Could not retrieve KaTeX auto render extension from CDN. Reason: %s." . -}}
45+
{{ else with .Value -}}
46+
{{ with resources.Copy ( printf "js/auto-render%s.js" (cond hugo.IsProduction ".min" "")) . }}
47+
{{ $secureJS := . | resources.Fingerprint "sha512" -}}
48+
<script defer src="{{- .RelPermalink -}}" integrity="{{- $secureJS.Data.Integrity -}}" crossorigin="anonymous"
49+
{{ printf "onload='renderMathInElement(%s, %s);'" (( $.Page.Site.Params.katex.html_dom_element | default "document.body" ) | safeJS ) ( printf "%s" ( $.Page.Site.Params.katex.options | jsonify )) | safeHTMLAttr -}} >
50+
</script>
51+
{{ end -}}
52+
{{ end -}}
53+
{{ else -}}
54+
{{ errorf "Invalid KaTeX version %s, could not retrieve this version from CDN." $version -}}
55+
{{ end -}}

‎layouts/_partials/scripts/mhchem.html‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
{{/* Add support for displaying chemical equations and physical units by loading the mhchem extension: */ -}}
2+
{{ $mhchem_url := printf "https://cdn.jsdelivr.net/npm/katex@%s/dist/contrib/mhchem%s.js" .version (cond hugo.IsProduction ".min" "") -}}
3+
{{ with try (resources.GetRemote $mhchem_url) -}}
4+
{{ with .Err -}}
5+
{{ errorf "Could not retrieve mhchem script from CDN. Reason: %s." . -}}
6+
{{ else with .Value -}}
7+
{{ with resources.Copy (printf "js/mhchem%s.js" (cond hugo.IsProduction ".min" "")) . }}
8+
{{ $secureJS := . | resources.Fingerprint "sha512" -}}
9+
<script defer src="{{- .RelPermalink -}}" integrity="{{- $secureJS.Data.Integrity -}}" crossorigin="anonymous" ></script>
10+
{{ end -}}
11+
{{ end -}}
12+
{{ else -}}
13+
{{ errorf "Invalid KaTeX version %s, could not retrieve this version from CDN." .version -}}
14+
{{ end -}}

‎userguide/content/en/blog/2023/bootstrap-5-migration.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -67,7 +67,7 @@ For details and an example, see:
6767

6868
- [Sass](https://getbootstrap.com/docs/5.2/migration/#sass) section of the
6969
migration page
70-
- [\[BSv5\] Adjust `media-breakpoint-down()` argument · Docsy PR #1367](https://github.com/google/docsy/pull/1367)
70+
- [[BSv5] Adjust `media-breakpoint-down()` argument · Docsy PR #1367](https://github.com/google/docsy/pull/1367)
7171

7272
### Grid `.row` and `.col` style changes are breaking
7373

@@ -111,11 +111,11 @@ updates and might impact Docsy-based projects as well:
111111

112112
References:
113113

114-
- [\[BSv5\] Row/col formatting breaks Docsy components #1466](https://github.com/google/docsy/issues/1466),
114+
- [[BSv5] Row/col formatting breaks Docsy components #1466](https://github.com/google/docsy/issues/1466),
115115
in particular
116-
- [\[BSv5\] Footer fixes: reset flex-shrink, and more·](https://github.com/google/docsy/pull/1373)
116+
- [[BSv5] Footer fixes: reset flex-shrink, and more·](https://github.com/google/docsy/pull/1373)
117117
[Docsy PR](https://github.com/google/docsy/pull/1367)[ #1373](https://github.com/google/docsy/pull/1373)
118-
- [\[BSv5\] Footer: drop flex-shrink tweak + other adjustments ·](https://github.com/google/docsy/pull/1523)
118+
- [[BSv5] Footer: drop flex-shrink tweak + other adjustments ·](https://github.com/google/docsy/pull/1523)
119119
[Docsy PR](https://github.com/google/docsy/pull/1367)[ #1523](https://github.com/google/docsy/pull/1523)
120120
- [Why are all col classes 'position: relative'? · Bootstrap v4 issue #25254](https://github.com/twbs/bootstrap/issues/25254)
121121
- [Why flex-shrink 0 for all columns? · Bootstrap discussion #37951](https://github.com/orgs/twbs/discussions/37951)
@@ -165,7 +165,7 @@ imports from
165165

166166
References:
167167

168-
- [\[BSv5\] Fix SCSS functions import issue ... ·](https://github.com/google/docsy/pull/1388)
168+
- [[BSv5] Fix SCSS functions import issue ... ·](https://github.com/google/docsy/pull/1388)
169169
[Docsy PR](https://github.com/google/docsy/pull/1367)
170170
[#1388](https://github.com/google/docsy/pull/1388)
171171
- [New \_maps.scss](https://getbootstrap.com/docs/5.2/migration/#new-_mapsscss)
@@ -227,7 +227,7 @@ Docsy house cleaning. For details concerning both breaking and non-breaking
227227
Docsy-specific changes, consult the
228228
[changelog](https://github.com/google/docsy/blob/main/CHANGELOG.md#070). In
229229
particular, one non-breaking but important change to be aware of is:
230-
[\[BSv5\] Docsy variables cleanup ... PR #1462](https://github.com/google/docsy/pull/1462).
230+
[[BSv5] Docsy variables cleanup ... PR #1462](https://github.com/google/docsy/pull/1462).
231231

232232
## Give it a try!
233233

0 commit comments

Comments
 (0)