-
Notifications
You must be signed in to change notification settings - Fork 482
/
HTMLWriter.jl
1949 lines (1707 loc) · 76.2 KB
/
HTMLWriter.jl
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
"""
A module for rendering `Document` objects to HTML.
# Keywords
[`HTMLWriter`](@ref) uses the following additional keyword arguments that can be passed to
[`Documenter.makedocs`](@ref): `authors`, `pages`, `sitename`, `version`.
The behavior of [`HTMLWriter`](@ref) can be further customized by setting the `format`
keyword of [`Documenter.makedocs`](@ref) to a [`HTML`](@ref), which accepts the following
keyword arguments: `analytics`, `assets`, `canonical`, `disable_git`, `edit_link`,
`prettyurls`, `collapselevel`, `sidebar_sitename`, `highlights`, `mathengine` and `footer`.
**`sitename`** is the site's title displayed in the title bar and at the top of the
*navigation menu. This argument is mandatory for [`HTMLWriter`](@ref).
**`pages`** defines the hierarchy of the navigation menu.
# Experimental keywords
**`version`** specifies the version string of the current version which will be the
selected option in the version selector. If this is left empty (default) the version
selector will be hidden. The special value `git-commit` sets the value in the output to
`git:{commit}`, where `{commit}` is the first few characters of the current commit hash.
# `HTML` `Plugin` options
The [`HTML`](@ref) [`Documenter.Plugin`](@ref) provides additional customization options
for the [`HTMLWriter`](@ref). For more information, see the [`HTML`](@ref) documentation.
# Page outline
The [`HTMLWriter`](@ref) makes use of the page outline that is determined by the
headings. It is assumed that if the very first block of a page is a level 1 heading,
then it is intended as the page title. This has two consequences:
1. It is then used to automatically determine the page title in the navigation menu
and in the `<title>` tag, unless specified in the `.pages` option.
2. If the first heading is interpreted as being the page title, it is not displayed
in the navigation sidebar.
"""
module HTMLWriter
using Dates: Dates, @dateformat_str, now
import Markdown
import JSON
import ...Documenter:
Anchors,
Builder,
Documents,
Expanders,
Documenter,
Utilities,
Writers
using ...Utilities: Default
using ...Utilities.JSDependencies: JSDependencies, json_jsescape
import ...Utilities.DOM: DOM, Tag, @tags
using ...Utilities.MDFlatten
export HTML
"Data attribute for the script inserting a wraning for outdated docs."
const OUTDATED_VERSION_ATTR = "data-outdated-warner"
"List of Documenter native themes."
const THEMES = ["documenter-light", "documenter-dark"]
"The root directory of the HTML assets."
const ASSETS = normpath(joinpath(@__DIR__, "..", "..", "assets", "html"))
"The directory where all the Sass/SCSS files needed for theme building are."
const ASSETS_SASS = joinpath(ASSETS, "scss")
"Directory for the compiled CSS files of the themes."
const ASSETS_THEMES = joinpath(ASSETS, "themes")
struct HTMLAsset
class :: Symbol
uri :: String
islocal :: Bool
function HTMLAsset(class::Symbol, uri::String, islocal::Bool)
if !islocal && match(r"^https?://", uri) === nothing
error("Remote asset URL must start with http:// or https://")
end
class in [:ico, :css, :js] || error("Unrecognised asset class $class for `$(uri)`")
new(class, uri, islocal)
end
end
"""
asset(uri)
Can be used to pass non-local web assets to [`HTML`](@ref), where `uri` should be an absolute
HTTP or HTTPS URL.
It accepts the following keyword arguments:
**`class`** can be used to override the asset class, which determines how exactly the asset
gets included in the HTML page. This is necessary if the class can not be determined
automatically (default).
Should be one of: `:js`, `:css` or `:ico`. They become a `<script>`,
`<link rel="stylesheet" type="text/css">` and `<link rel="icon" type="image/x-icon">`
elements in `<head>`, respectively.
**`islocal`** can be used to declare the asset to be local. The `uri` should then be a path
relative to the documentation source directory (conventionally `src/`). This can be useful
when it is necessary to override the asset class of a local asset.
# Usage
```julia
Documenter.HTML(assets = [
# Standard local asset
"assets/extra_styles.css",
# Standard remote asset (extension used to determine that class = :js)
asset("https://example.com/jslibrary.js"),
# Setting asset class manually, since it can't be determined manually
asset("https://example.com/fonts", class = :css),
# Same as above, but for a local asset
asset("asset/foo.script", class=:js, islocal=true),
])
```
"""
function asset(uri; class = nothing, islocal=false)
if class === nothing
class = assetclass(uri)
(class === nothing) && error("""
Unable to determine asset class for: $(uri)
It can be set explicitly with the `class` keyword argument.
""")
end
HTMLAsset(class, uri, islocal)
end
function assetclass(uri)
# TODO: support actual proper URIs
ext = splitext(uri)[end]
ext == ".ico" ? :ico :
ext == ".css" ? :css :
ext == ".js" ? :js : :unknown
end
abstract type MathEngine end
"""
KaTeX(config::Dict = <default>, override = false)
An instance of the `KaTeX` type can be passed to [`HTML`](@ref) via the `mathengine` keyword
to specify that the [KaTeX rendering engine](https://katex.org/) should be used in the HTML
output to render mathematical expressions.
A dictionary can be passed via the `config` argument to configure KaTeX. It becomes the
[options argument of `renderMathInElement`](https://katex.org/docs/autorender.html#api). By
default, Documenter only sets a custom `delimiters` option.
By default, the user-provided dictionary gets _merged_ with the default dictionary (i.e. the
resulting configuration dictionary will contain the values from both dictionaries, but e.g.
setting your own `delimiters` value will override the default). This can be overridden by
setting `override` to `true`, in which case the default values are ignored and only the
user-provided dictionary is used.
"""
struct KaTeX <: MathEngine
config :: Dict{Symbol,Any}
function KaTeX(config::Union{Dict,Nothing} = nothing, override=false)
default = Dict(
:delimiters => [
Dict(:left => raw"$", :right => raw"$", display => false),
Dict(:left => raw"$$", :right => raw"$$", display => true),
Dict(:left => raw"\[", :right => raw"\]", display => true),
]
)
new((config === nothing) ? default : override ? config : merge(default, config))
end
end
"""
MathJax2(config::Dict = <default>, override = false)
An instance of the `MathJax2` type can be passed to [`HTML`](@ref) via the `mathengine`
keyword to specify that the [MathJax v2 rendering engine](https://www.mathjax.org/) should be
used in the HTML output to render mathematical expressions.
A dictionary can be passed via the `config` argument to configure MathJax. It gets passed to
the [`MathJax.Hub.Config`](https://docs.mathjax.org/en/v2.7-latest/options/) function. By
default, Documenter sets custom configurations for `tex2jax`, `config`, `jax`, `extensions`
and `Tex`.
By default, the user-provided dictionary gets _merged_ with the default dictionary (i.e. the
resulting configuration dictionary will contain the values from both dictionaries, but e.g.
setting your own `tex2jax` value will override the default). This can be overridden by
setting `override` to `true`, in which case the default values are ignored and only the
user-provided dictionary is used.
The URL of the MathJax JS file can be overridden using the `url` keyword argument (e.g. to
use a particular minor version).
"""
struct MathJax2 <: MathEngine
config :: Dict{Symbol,Any}
url :: String
function MathJax2(config::Union{Dict,Nothing} = nothing, override=false; url = "")
default = Dict(
:tex2jax => Dict(
"inlineMath" => [["\$","\$"], ["\\(","\\)"]],
"processEscapes" => true
),
:config => ["MMLorHTML.js"],
:jax => [
"input/TeX",
"output/HTML-CSS",
"output/NativeMML"
],
:extensions => [
"MathMenu.js",
"MathZoom.js",
"TeX/AMSmath.js",
"TeX/AMSsymbols.js",
"TeX/autobold.js",
"TeX/autoload-all.js"
],
:TeX => Dict(:equationNumbers => Dict(:autoNumber => "AMS"))
)
new((config === nothing) ? default : override ? config : merge(default, config), url)
end
end
@deprecate MathJax(config::Union{Dict,Nothing} = nothing, override=false) MathJax2(config, override) false
@doc "deprecated – Use [`MathJax2`](@ref) instead" MathJax
"""
MathJax3(config::Dict = <default>, override = false)
An instance of the `MathJax3` type can be passed to [`HTML`](@ref) via the `mathengine`
keyword to specify that the [MathJax v3 rendering engine](https://www.mathjax.org/) should be
used in the HTML output to render mathematical expressions.
A dictionary can be passed via the `config` argument to configure MathJax. It gets passed to
[`Window.MathJax`](https://docs.mathjax.org/en/latest/options/) function. By default,
Documenter specifies in the key `tex` that `\$...\$` and `\\(...\\)` denote inline math, that AMS
style tags should be used and the `base`, `ams` and `autoload` packages should be imported.
The key `options`, by default, specifies which HTML classes to ignore and which to process
using MathJax.
By default, the user-provided dictionary gets _merged_ with the default dictionary (i.e. the
resulting configuration dictionary will contain the values from both dictionaries, but e.g.
setting your own `tex` value will override the default). This can be overridden by
setting `override` to `true`, in which case the default values are ignored and only the
user-provided dictionary is used.
The URL of the MathJax JS file can be overridden using the `url` keyword argument (e.g. to
use a particular minor version).
"""
struct MathJax3 <: MathEngine
config :: Dict{Symbol,Any}
url :: String
function MathJax3(config::Union{Dict,Nothing} = nothing, override=false; url = "")
default = Dict(
:tex => Dict(
"inlineMath" => [["\$","\$"], ["\\(","\\)"]],
"tags" => "ams",
"packages" => ["base", "ams", "autoload"],
),
:options => Dict(
"ignoreHtmlClass" => "tex2jax_ignore",
"processHtmlClass" => "tex2jax_process",
)
)
new((config === nothing) ? default : override ? config : merge(default, config), url)
end
end
"""
HTML(kwargs...)
Sets the behavior of [`HTMLWriter`](@ref).
# Keyword arguments
**`prettyurls`** (default `true`) -- allows toggling the pretty URLs feature.
By default (i.e. when `prettyurls` is set to `true`), Documenter creates a directory
structure that hides the `.html` suffixes from the URLs (e.g. by default `src/foo.md`
becomes `src/foo/index.html`, but can be accessed with via `src/foo/` in the browser). This
structure is preferred when publishing the generate HTML files as a website (e.g. on GitHub
Pages), which is Documenter's primary use case.
If `prettyurls = false`, then Documenter generates `src/foo.html` instead, suitable for
local documentation builds, as browsers do not normally resolve `foo/` to `foo/index.html`
for local files.
To have pretty URLs disabled in local builds, but still have them enabled for the automatic
CI deployment builds, you can set `prettyurls = get(ENV, "CI", nothing) == "true"` (the
specific environment variable you will need to check may depend on the CI system you are
using, but this will work on Travis CI).
**`disable_git`** can be used to disable calls to `git` when the document is not
in a Git-controlled repository. Without setting this to `true`, Documenter will throw
an error and exit if any of the Git commands fail. The calls to Git are mainly used to
gather information about the current commit hash and file paths, necessary for constructing
the links to the remote repository.
**`edit_link`** can be used to specify which branch, tag or commit (when passed a `String`)
in the remote repository the "Edit on ..." links point to. If a special `Symbol` value
`:commit` is passed, the current commit will be used instead. If set to `nothing`, the
link edit link will be hidden altogether. Default value is `"master"`, making the edit link
point to the master branch.
**`canonical`** specifies the canonical URL for your documentation. We recommend
you set this to the base url of your stable documentation, e.g. `https://juliadocs.github.io/Documenter.jl/stable`.
This allows search engines to know which version to send their users to. [See
wikipedia for more information](https://en.wikipedia.org/wiki/Canonical_link_element).
Default is `nothing`, in which case no canonical link is set.
**`analytics`** can be used specify the Google Analytics tracking ID.
**`assets`** can be used to include additional assets (JS, CSS, ICO etc. files). See below
for more information.
**`sidebar_sitename`** determines whether the site name is shown in the sidebar or not.
Setting it to `false` can be useful when the logo already contains the name of the package.
Defaults to `true`.
**`highlights`** can be used to add highlighting for additional languages. By default,
Documenter already highlights all the ["Common" highlight.js](https://highlightjs.org/download/)
languages and Julia (`julia`, `julia-repl`). Additional languages must be specified by"
their filenames as they appear on [CDNJS](https://cdnjs.com/libraries/highlight.js) for the
highlight.js version Documenter is using. E.g. to include highlighting for YAML and LLVM IR,
you would set `highlights = ["llvm", "yaml"]`. Note that no verification is done whether the
provided language names are sane.
**`mathengine`** specifies which LaTeX rendering engine will be used to render the math
blocks. The options are either [KaTeX](https://katex.org/) (default),
[MathJax v2](https://www.mathjax.org/), or [MathJax v3](https://www.mathjax.org/), enabled by
passing an instance of [`KaTeX`](@ref), [`MathJax2`](@ref), or
[`MathJax3`](@ref) objects, respectively. The rendering engine can further be customized by
passing options to the [`KaTeX`](@ref) or [`MathJax2`](@ref)/[`MathJax3`](@ref) constructors.
**`lang`** specifies the [`lang` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang)
of the top-level `<html>` element, declaring the language of the generated pages. The default
value is `"en"`.
**`footer`** can be a valid single-line markdown `String` or `nothing` and is displayed below
the page navigation. Defaults to `"Powered by [Documenter.jl](https://github.com/JuliaDocs/Documenter.jl)
and the [Julia Programming Language](https://julialang.org/)."`.
**`warn_outdated`** inserts a warning if the current page is not the newest version of the
documentation.
# Default and custom assets
Documenter copies all files under the source directory (e.g. `/docs/src/`) over
to the compiled site. It also copies a set of default assets from `/assets/html/`
to the site's `assets/` directory, unless the user already had a file with the
same name, in which case the user's files overrides the Documenter's file.
This could, in principle, be used for customizing the site's style and scripting.
The HTML output also links certain custom assets to the generated HTML documents,
specifically a logo and additional javascript files.
The asset files that should be linked must be placed in `assets/`, under the source
directory (e.g `/docs/src/assets`) and must be on the top level (i.e. files in
the subdirectories of `assets/` are not linked).
For the **logo**, Documenter checks for the existence of `assets/logo.{svg,png,webp,gif,jpg,jpeg}`,
in this order. The first one it finds gets displayed at the top of the navigation sidebar.
It will also check for `assets/logo-dark.{svg,png,webp,gif,jpg,jpeg}` and use that for dark
themes.
Additional JS, ICO, and CSS assets can be included in the generated pages by passing them as
a list with the `assets` keyword. Each asset will be included in the `<head>` of every page
in the order in which they are given. The type of the asset (i.e. whether it is going to be
included with a `<script>` or a `<link>` tag) is determined by the file's extension --
either `.js`, `.ico`[^1], or `.css` (unless overridden with [`asset`](@ref)).
Simple strings are assumed to be local assets and that each correspond to a file relative to
the documentation source directory (conventionally `src/`). Non-local assets, identified by
their absolute URLs, can be included with the [`asset`](@ref) function.
[^1]: Adding an ICO asset is primarily useful for setting a custom `favicon`.
"""
struct HTML <: Documenter.Writer
prettyurls :: Bool
disable_git :: Bool
edit_link :: Union{String, Symbol, Nothing}
canonical :: Union{String, Nothing}
assets :: Vector{HTMLAsset}
analytics :: String
collapselevel :: Int
sidebar_sitename :: Bool
highlights :: Vector{String}
mathengine :: Union{MathEngine,Nothing}
footer :: Union{Markdown.MD, Nothing}
lang :: String
warn_outdated :: Bool
function HTML(;
prettyurls :: Bool = true,
disable_git :: Bool = false,
edit_link :: Union{String, Symbol, Nothing, Default} = Default("master"),
canonical :: Union{String, Nothing} = nothing,
assets :: Vector = String[],
analytics :: String = "",
collapselevel :: Integer = 2,
sidebar_sitename :: Bool = true,
highlights :: Vector{String} = String[],
mathengine :: Union{MathEngine,Nothing} = KaTeX(),
footer :: Union{String, Nothing} = "Powered by [Documenter.jl](https://github.com/JuliaDocs/Documenter.jl) and the [Julia Programming Language](https://julialang.org/).",
# deprecated keywords
edit_branch :: Union{String, Nothing, Default} = Default(nothing),
lang :: String = "en",
warn_outdated :: Bool = true
)
collapselevel >= 1 || throw(ArgumentError("collapselevel must be >= 1"))
assets = map(assets) do asset
isa(asset, HTMLAsset) && return asset
isa(asset, AbstractString) && return HTMLAsset(assetclass(asset), asset, true)
error("Invalid value in assets: $(asset) [$(typeof(asset))]")
end
# Handle edit_branch deprecation
if !isa(edit_branch, Default)
isa(edit_link, Default) || error("Can't specify edit_branch (deprecated) and edit_link simultaneously")
@warn """
The edit_branch keyword is deprecated -- use edit_link instead.
Note: `edit_branch = nothing` must be changed to `edit_link = :commit`.
"""
edit_link = (edit_branch === nothing) ? :commit : edit_branch
end
if isa(edit_link, Symbol) && (edit_link !== :commit)
throw(ArgumentError("Invalid symbol (:$edit_link) passed to edit_link."))
end
if footer !== nothing
footer = Markdown.parse(footer)
if !(length(footer.content) == 1 && footer.content[1] isa Markdown.Paragraph)
throw(ArgumentError("footer must be a single-line markdown compatible string."))
end
end
isa(edit_link, Default) && (edit_link = edit_link[])
new(prettyurls, disable_git, edit_link, canonical, assets, analytics,
collapselevel, sidebar_sitename, highlights, mathengine, footer, lang, warn_outdated)
end
end
"Provides a namespace for remote dependencies."
module RD
using JSON
using ....Utilities.JSDependencies: RemoteLibrary, Snippet, RequireJS, jsescape, json_jsescape
using ..HTMLWriter: KaTeX, MathJax, MathJax2, MathJax3
const requirejs_cdn = "https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js"
const lato = "https://cdnjs.cloudflare.com/ajax/libs/lato-font/3.0.0/css/lato-font.min.css"
const juliamono = "https://cdnjs.cloudflare.com/ajax/libs/juliamono/0.039/juliamono-regular.css"
const fontawesome_version = "5.15.3"
const fontawesome_css = [
"https://cdnjs.cloudflare.com/ajax/libs/font-awesome/$(fontawesome_version)/css/fontawesome.min.css",
"https://cdnjs.cloudflare.com/ajax/libs/font-awesome/$(fontawesome_version)/css/solid.min.css",
"https://cdnjs.cloudflare.com/ajax/libs/font-awesome/$(fontawesome_version)/css/brands.min.css",
]
const jquery = RemoteLibrary("jquery", "https://cdnjs.cloudflare.com/ajax/libs/jquery/3.6.0/jquery.min.js")
const jqueryui = RemoteLibrary("jqueryui", "https://cdnjs.cloudflare.com/ajax/libs/jqueryui/1.12.1/jquery-ui.min.js")
const lunr = RemoteLibrary("lunr", "https://cdnjs.cloudflare.com/ajax/libs/lunr.js/2.3.9/lunr.min.js")
const lodash = RemoteLibrary("lodash", "https://cdnjs.cloudflare.com/ajax/libs/lodash.js/4.17.21/lodash.min.js")
# headroom
const headroom_version = "0.12.0"
const headroom = RemoteLibrary("headroom", "https://cdnjs.cloudflare.com/ajax/libs/headroom/$(headroom_version)/headroom.min.js")
const headroom_jquery = RemoteLibrary(
"headroom-jquery",
"https://cdnjs.cloudflare.com/ajax/libs/headroom/$(headroom_version)/jQuery.headroom.min.js",
deps = ["jquery", "headroom"],
)
# highlight.js
"Add the highlight.js dependencies and snippet to a [`RequireJS`](@ref) declaration."
function highlightjs!(r::RequireJS, languages = String[])
# NOTE: the CSS themes for hightlightjs are compiled into the Documenter CSS
# When updating this dependency, it is also necessary to update the the CSS
# files the CSS files in assets/html/scss/highlightjs
hljs_version = "11.0.1"
push!(r, RemoteLibrary(
"highlight",
"https://cdnjs.cloudflare.com/ajax/libs/highlight.js/$(hljs_version)/highlight.min.js"
))
prepend!(languages, ["julia", "julia-repl"])
for language in languages
language = jsescape(language)
push!(r, RemoteLibrary(
"highlight-$(language)",
"https://cdnjs.cloudflare.com/ajax/libs/highlight.js/$(hljs_version)/languages/$(language).min.js",
deps = ["highlight"]
))
end
push!(r, Snippet(
vcat(["jquery", "highlight"], ["highlight-$(jsescape(language))" for language in languages]),
["\$"],
raw"""
$(document).ready(function() {
hljs.highlightAll();
})
"""
))
end
# MathJax & KaTeX
const katex_version = "0.13.11"
const katex_css = "https://cdnjs.cloudflare.com/ajax/libs/KaTeX/$(katex_version)/katex.min.css"
function mathengine!(r::RequireJS, engine::KaTeX)
push!(r, RemoteLibrary(
"katex",
"https://cdnjs.cloudflare.com/ajax/libs/KaTeX/$(katex_version)/katex.min.js"
))
push!(r, RemoteLibrary(
"katex-auto-render",
"https://cdnjs.cloudflare.com/ajax/libs/KaTeX/$(katex_version)/contrib/auto-render.min.js",
deps = ["katex"],
))
push!(r, Snippet(
["jquery", "katex", "katex-auto-render"],
["\$", "katex", "renderMathInElement"],
"""
\$(document).ready(function() {
renderMathInElement(
document.body,
$(json_jsescape(engine.config, 2))
);
})
"""
))
end
function mathengine!(r::RequireJS, engine::MathJax2)
url = isempty(engine.url) ? "https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.7/MathJax.js?config=TeX-AMS_HTML" : engine.url
push!(r, RemoteLibrary(
"mathjax",
url,
exports = "MathJax"
))
push!(r, Snippet(["mathjax"], ["MathJax"],
"""
MathJax.Hub.Config($(json_jsescape(engine.config, 2)));
"""
))
end
function mathengine!(r::RequireJS, engine::MathJax3)
url = isempty(engine.url) ? "https://cdnjs.cloudflare.com/ajax/libs/mathjax/3.1.4/es5/tex-svg.js" : engine.url
push!(r, Snippet([], [],
"""
window.MathJax = $(json_jsescape(engine.config, 2));
(function () {
var script = document.createElement('script');
script.src = '$url';
script.async = true;
document.head.appendChild(script);
})();
"""
))
end
mathengine(::RequireJS, ::Nothing) = nothing
end
struct SearchRecord
src :: String
page :: Documents.Page
fragment :: String
category :: String
title :: String
page_title :: String
text :: String
end
"""
[`HTMLWriter`](@ref)-specific globals that are passed to [`domify`](@ref) and
other recursive functions.
"""
mutable struct HTMLContext
doc :: Documents.Document
settings :: HTML
scripts :: Vector{String}
documenter_js :: String
themeswap_js :: String
warner_js :: String
search_js :: String
search_index :: Vector{SearchRecord}
search_index_js :: String
search_navnode :: Documents.NavNode
footnotes :: Vector{Markdown.Footnote}
end
HTMLContext(doc, settings=HTML()) = HTMLContext(doc, settings, [], "", "", "", "", [], "", Documents.NavNode("search", "Search", nothing), [])
function SearchRecord(ctx::HTMLContext, navnode; fragment="", title=nothing, category="page", text="")
page_title = mdflatten(pagetitle(ctx, navnode))
if title === nothing
title = page_title
end
SearchRecord(
pretty_url(ctx, get_url(ctx, navnode.page)),
getpage(ctx, navnode),
fragment,
lowercase(category),
title,
page_title,
text
)
end
function SearchRecord(ctx::HTMLContext, navnode, node::Markdown.Header)
a = getpage(ctx, navnode).mapping[node]
SearchRecord(ctx, navnode;
fragment=Anchors.fragment(a),
title=mdflatten(node),
category="section")
end
function SearchRecord(ctx, navnode, node)
SearchRecord(ctx, navnode; text=mdflatten(node))
end
function JSON.lower(rec::SearchRecord)
# Replace any backslashes in links, if building the docs on Windows
src = replace(rec.src, '\\' => '/')
ref = string(src, rec.fragment)
Dict{String, String}(
"location" => ref,
"page" => rec.page_title,
"title" => rec.title,
"category" => rec.category,
"text" => rec.text
)
end
"""
Returns a page (as a [`Documents.Page`](@ref) object) using the [`HTMLContext`](@ref).
"""
getpage(ctx, path) = ctx.doc.blueprint.pages[path]
getpage(ctx, navnode::Documents.NavNode) = getpage(ctx, navnode.page)
function render(doc::Documents.Document, settings::HTML=HTML())
@info "HTMLWriter: rendering HTML pages."
!isempty(doc.user.sitename) || error("HTML output requires `sitename`.")
if isempty(doc.blueprint.pages)
error("Aborting HTML build: no pages under src/")
elseif !haskey(doc.blueprint.pages, "index.md")
@warn "Can't generate landing page (index.html): src/index.md missing" keys(doc.blueprint.pages)
end
ctx = HTMLContext(doc, settings)
ctx.search_index_js = "search_index.js"
ctx.themeswap_js = copy_asset("themeswap.js", doc)
ctx.warner_js = copy_asset("warner.js", doc)
# Generate documenter.js file with all the JS dependencies
ctx.documenter_js = "assets/documenter.js"
if isfile(joinpath(doc.user.source, "assets", "documenter.js"))
@warn "not creating 'documenter.js', provided by the user."
else
r = JSDependencies.RequireJS([
RD.jquery, RD.jqueryui, RD.headroom, RD.headroom_jquery,
])
RD.mathengine!(r, settings.mathengine)
RD.highlightjs!(r, settings.highlights)
for filename in readdir(joinpath(ASSETS, "js"))
path = joinpath(ASSETS, "js", filename)
endswith(filename, ".js") && isfile(path) || continue
push!(r, JSDependencies.parse_snippet(path))
end
JSDependencies.verify(r; verbose=true) || error("RequireJS declaration is invalid")
JSDependencies.writejs(joinpath(doc.user.build, "assets", "documenter.js"), r)
end
# Generate search.js file with all the JS dependencies
ctx.search_js = "assets/search.js"
if isfile(joinpath(doc.user.source, "assets", "search.js"))
@warn "not creating 'search.js', provided by the user."
else
r = JSDependencies.RequireJS([RD.jquery, RD.lunr, RD.lodash])
push!(r, JSDependencies.parse_snippet(joinpath(ASSETS, "search.js")))
JSDependencies.verify(r; verbose=true) || error("RequireJS declaration is invalid")
JSDependencies.writejs(joinpath(doc.user.build, "assets", "search.js"), r)
end
for theme in THEMES
copy_asset("themes/$(theme).css", doc)
end
for page in keys(doc.blueprint.pages)
idx = findfirst(nn -> nn.page == page, doc.internal.navlist)
nn = (idx === nothing) ? Documents.NavNode(page, nothing, nothing) : doc.internal.navlist[idx]
@debug "Rendering $(page) [$(repr(idx))]"
render_page(ctx, nn)
end
render_search(ctx)
open(joinpath(doc.user.build, ctx.search_index_js), "w") do io
println(io, "var documenterSearchIndex = {\"docs\":")
# convert Vector{SearchRecord} to a JSON string + do additional JS escaping
println(io, json_jsescape(ctx.search_index), "\n}")
end
end
"""
Copies an asset from Documenters `assets/html/` directory to `doc.user.build`.
Returns the path of the copied asset relative to `.build`.
"""
function copy_asset(file, doc)
src = joinpath(Utilities.assetsdir(), "html", file)
alt_src = joinpath(doc.user.source, "assets", file)
dst = joinpath(doc.user.build, "assets", file)
isfile(src) || error("Asset '$file' not found at $(abspath(src))")
# Since user's alternative assets are already copied over in a previous build
# step and they should override Documenter's original assets, we only actually
# perform the copy if <source>/assets/<file> does not exist. Note that checking
# the existence of <build>/assets/<file> is not sufficient since the <build>
# directory might be dirty from a previous build.
if isfile(alt_src)
@warn "not copying '$src', provided by the user."
else
ispath(dirname(dst)) || mkpath(dirname(dst))
ispath(dst) && @warn "overwriting '$dst'."
# Files in the Documenter folder itself are read-only when
# Documenter is Pkg.added so we create a new file to get
# correct file permissions.
open(io -> write(dst, io), src, "r")
end
assetpath = normpath(joinpath("assets", file))
# Replace any backslashes in links, if building the docs on Windows
return replace(assetpath, '\\' => '/')
end
# Page
# ------------------------------------------------------------------------------
## Standard page
"""
Constructs and writes the page referred to by the `navnode` to `.build`.
"""
function render_page(ctx, navnode)
@tags html div body
page = getpage(ctx, navnode)
head = render_head(ctx, navnode)
sidebar = render_sidebar(ctx, navnode)
navbar = render_navbar(ctx, navnode, true)
article = render_article(ctx, navnode)
footer = render_footer(ctx, navnode)
htmldoc = render_html(ctx, navnode, head, sidebar, navbar, article, footer)
open_output(ctx, navnode) do io
print(io, htmldoc)
end
end
## Search page
function render_search(ctx)
@tags article body h1 header hr html li nav p span ul script
src = get_url(ctx, ctx.search_navnode)
head = render_head(ctx, ctx.search_navnode)
sidebar = render_sidebar(ctx, ctx.search_navnode)
navbar = render_navbar(ctx, ctx.search_navnode, false)
article = article(
p["#documenter-search-info"]("Loading search..."),
ul["#documenter-search-results"]
)
footer = render_footer(ctx, ctx.search_navnode)
scripts = [
script[:src => relhref(src, ctx.search_index_js)],
script[:src => relhref(src, ctx.search_js)],
]
htmldoc = render_html(ctx, ctx.search_navnode, head, sidebar, navbar, article, footer, scripts)
open_output(ctx, ctx.search_navnode) do io
print(io, htmldoc)
end
end
## Rendering HTML elements
# ------------------------------------------------------------------------------
"""
Renders the main `<html>` tag.
"""
function render_html(ctx, navnode, head, sidebar, navbar, article, footer, scripts::Vector{DOM.Node}=DOM.Node[])
@tags html body div
DOM.HTMLDocument(
html[:lang=>ctx.settings.lang](
head,
body(
div["#documenter"](
sidebar,
div[".docs-main"](navbar, article, footer),
render_settings(ctx),
),
),
scripts...
)
)
end
"""
Renders the modal settings dialog.
"""
function render_settings(ctx)
@tags div header section footer p button hr span select option label a
theme_selector = p(
label[".label"]("Theme"),
div[".select"](
select["#documenter-themepicker"](option[:value=>theme](theme) for theme in THEMES)
)
)
now_full, now_short = Dates.format(now(), dateformat"E d U Y HH:MM"), Dates.format(now(), dateformat"E d U Y")
buildinfo = p(
"This document was generated with ",
a[:href => "https://github.com/JuliaDocs/Documenter.jl"]("Documenter.jl"),
" on ",
span[".colophon-date", :title => now_full](now_short),
". ",
"Using Julia version $(Base.VERSION)."
)
div["#documenter-settings.modal"](
div[".modal-background"],
div[".modal-card"](
header[".modal-card-head"](
p[".modal-card-title"]("Settings"),
button[".delete"]()
),
section[".modal-card-body"](
theme_selector, hr(), buildinfo
),
footer[".modal-card-foot"]()
)
)
end
function render_head(ctx, navnode)
@tags head meta link script title
src = get_url(ctx, navnode)
page_title = "$(mdflatten(pagetitle(ctx, navnode))) · $(ctx.doc.user.sitename)"
css_links = [
RD.lato,
RD.juliamono,
RD.fontawesome_css...,
RD.katex_css,
]
head(
meta[:charset=>"UTF-8"],
meta[:name => "viewport", :content => "width=device-width, initial-scale=1.0"],
title(page_title),
analytics_script(ctx.settings.analytics),
warning_script(src, ctx),
canonical_link_element(ctx.settings.canonical, pretty_url(ctx, src)),
# Stylesheets.
map(css_links) do each
link[:href => each, :rel => "stylesheet", :type => "text/css"]
end,
script("documenterBaseURL=\"$(relhref(src, "."))\""),
script[
:src => RD.requirejs_cdn,
Symbol("data-main") => relhref(src, ctx.documenter_js)
],
script[:src => relhref(src, "siteinfo.js")],
script[:src => relhref(src, "../versions.js")],
# Themes. Note: we reverse the list to make sure that the default theme (first in
# the array) comes as the last <link> tag.
map(Iterators.reverse(enumerate(THEMES))) do (i, theme)
e = link[".docs-theme-link",
:rel => "stylesheet", :type => "text/css",
:href => relhref(src, "assets/themes/$(theme).css"),
Symbol("data-theme-name") => theme,
]
(i == 1) && push!(e.attributes, Symbol("data-theme-primary") => "")
(i == 2) && push!(e.attributes, Symbol("data-theme-primary-dark") => "")
return e
end,
script[:src => relhref(src, ctx.themeswap_js)],
# Custom user-provided assets.
asset_links(src, ctx.settings.assets),
)
end
function asset_links(src::AbstractString, assets::Vector{HTMLAsset})
@tags link script
links = DOM.Node[]
for asset in assets
class = asset.class
url = asset.islocal ? relhref(src, asset.uri) : asset.uri
node =
class == :ico ? link[:href => url, :rel => "icon", :type => "image/x-icon"] :
class == :css ? link[:href => url, :rel => "stylesheet", :type => "text/css"] :
class == :js ? script[:src => url] : continue # Skip non-js/css files.
push!(links, node)
end
return links
end
function analytics_script(tracking_id::AbstractString)
@tags script
isempty(tracking_id) ? Tag(Symbol("#RAW#"))("") : [
script[:async, :src => "https://www.googletagmanager.com/gtag/js?id=$(tracking_id)"](),
script("""
window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}
gtag('js', new Date());
gtag('config', '$(tracking_id)', {'page_path': location.pathname + location.search + location.hash});
""")
]
end
function warning_script(src, ctx)
if ctx.settings.warn_outdated
return Tag(:script)[Symbol(OUTDATED_VERSION_ATTR), :src => relhref(src, ctx.warner_js)]()
end
return Tag(Symbol("#RAW#"))("")
end
function canonical_link_element(canonical_link, src)
@tags link
if canonical_link === nothing
return Tag(Symbol("#RAW#"))("")
else
canonical_link_stripped = rstrip(canonical_link, '/')
href = "$canonical_link_stripped/$src"
return link[:rel => "canonical", :href => href]
end
end
# Navigation menu
# ------------------------------------------------------------------------------
struct NavMenuContext
htmlctx :: HTMLContext
current :: Documents.NavNode
idstack :: Vector{Int}
end
NavMenuContext(ctx::HTMLContext, current::Documents.NavNode) = NavMenuContext(ctx, current, [])
function render_sidebar(ctx, navnode)
@tags a form img input nav div select option span
src = get_url(ctx, navnode)
navmenu = nav[".docs-sidebar"]
# The logo and sitename will point to the first page in the navigation menu
href = navhref(ctx, first(ctx.doc.internal.navlist), navnode)
# Logo
logo = find_image_asset(ctx, "logo")
logo_dark = find_image_asset(ctx, "logo-dark")
if logo !== nothing
alt = isempty(ctx.doc.user.sitename) ? "Logo" : "$(ctx.doc.user.sitename) logo"
logo_element = a[".docs-logo", :href => href]
if logo_dark === nothing
push!(logo_element.nodes, img[:src => relhref(src, logo), :alt => alt])
else
push!(logo_element.nodes, img[".docs-light-only", :src => relhref(src, logo), :alt => alt])
push!(logo_element.nodes, img[".docs-dark-only", :src => relhref(src, logo_dark), :alt => alt])
end
push!(navmenu.nodes, logo_element)
end
# Sitename
if ctx.settings.sidebar_sitename
push!(navmenu.nodes, div[".docs-package-name"](
span[".docs-autofit"](a[:href => href](ctx.doc.user.sitename))
))
end
# Search box
push!(navmenu.nodes,
form[".docs-search", :action => navhref(ctx, ctx.search_navnode, navnode)](
input[
"#documenter-search-query.docs-search-query",
:name => "q",
:type => "text",
:placeholder => "Search docs",
],
)
)
# The menu itself
menu = navitem(NavMenuContext(ctx, navnode))
push!(menu.attributes, :class => "docs-menu")
push!(navmenu.nodes, menu)
# Version selector
let
vs_class = ".docs-version-selector.field.has-addons"
vs_label = span[".docs-label.button.is-static.is-size-7"]("Version")
vs_label = div[".control"](vs_label)
vs_select = select["#documenter-version-selector"]
if !isempty(ctx.doc.user.version)
vs_class = "$(vs_class).visible"
opt = option[:value => "#", :selected => "selected", ](ctx.doc.user.version)
vs_select = vs_select(opt)