-
Notifications
You must be signed in to change notification settings - Fork 0
/
print.html
1766 lines (1631 loc) · 92 KB
/
print.html
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
<!DOCTYPE HTML>
<html lang="en" class="sidebar-visible no-js light">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>mdBook Documentation</title>
<meta name="robots" content="noindex" />
<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
<meta name="description" content="Create book from markdown files. Like Gitbook but implemented in Rust">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="theme-color" content="#ffffff" />
<link rel="shortcut icon" href="favicon.png">
<link rel="stylesheet" href="css/variables.css">
<link rel="stylesheet" href="css/general.css">
<link rel="stylesheet" href="css/chrome.css">
<link rel="stylesheet" href="css/print.css" media="print">
<!-- Fonts -->
<link rel="stylesheet" href="FontAwesome/css/font-awesome.css">
<link href="https://fonts.googleapis.com/css?family=Open+Sans:300italic,400italic,600italic,700italic,800italic,400,300,600,700,800" rel="stylesheet" type="text/css">
<link href="https://fonts.googleapis.com/css?family=Source+Code+Pro:500" rel="stylesheet" type="text/css">
<!-- Highlight.js Stylesheets -->
<link rel="stylesheet" href="highlight.css">
<link rel="stylesheet" href="tomorrow-night.css">
<link rel="stylesheet" href="ayu-highlight.css">
<!-- Custom theme stylesheets -->
<link rel="stylesheet" href="theme/rtl.css">
<!-- MathJax -->
<script async type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
</head>
<body>
<!-- Provide site root to javascript -->
<script type="text/javascript">
var path_to_root = "";
var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "light" : "light";
</script>
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script type="text/javascript">
try {
var theme = localStorage.getItem('mdbook-theme');
var sidebar = localStorage.getItem('mdbook-sidebar');
if (theme.startsWith('"') && theme.endsWith('"')) {
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
}
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
}
} catch (e) { }
</script>
<!-- Set the theme before any content is loaded, prevents flash -->
<script type="text/javascript">
var theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
var html = document.querySelector('html');
html.classList.remove('no-js')
html.classList.remove('light')
html.classList.add(theme);
html.classList.add('js');
</script>
<!-- Hide / unhide sidebar before it is displayed -->
<script type="text/javascript">
var html = document.querySelector('html');
var sidebar = 'hidden';
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
}
html.classList.remove('sidebar-visible');
html.classList.add("sidebar-" + sidebar);
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<div class="sidebar-scrollbox">
<ol class="chapter"><li class="chapter-item expanded "><a href="index.html"><strong aria-hidden="true">1.</strong> mdBook</a></li><li class="chapter-item expanded "><a href="cli/index.html"><strong aria-hidden="true">2.</strong> Command Line Tool</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="cli/init.html"><strong aria-hidden="true">2.1.</strong> init</a></li><li class="chapter-item expanded "><a href="cli/build.html"><strong aria-hidden="true">2.2.</strong> build</a></li><li class="chapter-item expanded "><a href="cli/watch.html"><strong aria-hidden="true">2.3.</strong> watch</a></li><li class="chapter-item expanded "><a href="cli/serve.html"><strong aria-hidden="true">2.4.</strong> serve</a></li><li class="chapter-item expanded "><a href="cli/test.html"><strong aria-hidden="true">2.5.</strong> test</a></li><li class="chapter-item expanded "><a href="cli/clean.html"><strong aria-hidden="true">2.6.</strong> clean</a></li></ol></li><li class="chapter-item expanded "><a href="format/index.html"><strong aria-hidden="true">3.</strong> Format</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="format/summary.html"><strong aria-hidden="true">3.1.</strong> SUMMARY.md</a></li><li class="chapter-item expanded "><a href="format/config.html"><strong aria-hidden="true">3.2.</strong> Configuration</a></li><li class="chapter-item expanded "><a href="format/theme/index.html"><strong aria-hidden="true">3.3.</strong> Theme</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="format/theme/index-hbs.html"><strong aria-hidden="true">3.3.1.</strong> index.hbs</a></li><li class="chapter-item expanded "><a href="format/theme/syntax-highlighting.html"><strong aria-hidden="true">3.3.2.</strong> Syntax highlighting</a></li><li class="chapter-item expanded "><a href="format/theme/editor.html"><strong aria-hidden="true">3.3.3.</strong> Editor</a></li></ol></li><li class="chapter-item expanded "><a href="format/mathjax.html"><strong aria-hidden="true">3.4.</strong> MathJax Support</a></li><li class="chapter-item expanded "><a href="format/mdbook.html"><strong aria-hidden="true">3.5.</strong> mdBook specific features</a></li></ol></li><li class="chapter-item expanded "><a href="continuous-integration.html"><strong aria-hidden="true">4.</strong> Continuous Integration</a></li><li class="chapter-item expanded "><a href="for_developers/index.html"><strong aria-hidden="true">5.</strong> For Developers</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="for_developers/preprocessors.html"><strong aria-hidden="true">5.1.</strong> Preprocessors</a></li><li class="chapter-item expanded "><a href="for_developers/backends.html"><strong aria-hidden="true">5.2.</strong> Alternative Backends</a></li><li class="spacer"></li></ol></li><li class="chapter-item expanded "><a href="misc/contributors.html">Contributors</a></li></ol>
</div>
<div id="sidebar-resize-handle" class="sidebar-resize-handle"></div>
</nav>
<div id="page-wrapper" class="page-wrapper">
<div class="page">
<div id="menu-bar-hover-placeholder"></div>
<div id="menu-bar" class="menu-bar sticky bordered">
<div class="left-buttons">
<button id="sidebar-toggle" class="icon-button" type="button" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</button>
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
<i class="fa fa-paint-brush"></i>
</button>
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
<li role="none"><button role="menuitem" class="theme" id="light">Light (default)</button></li>
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
</ul>
<button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
<i class="fa fa-search"></i>
</button>
</div>
<h1 class="menu-title">mdBook Documentation</h1>
<div class="right-buttons">
<a href="print.html" title="Print this book" aria-label="Print this book">
<i id="print-button" class="fa fa-print"></i>
</a>
</div>
</div>
<div id="search-wrapper" class="hidden">
<form id="searchbar-outer" class="searchbar-outer">
<input type="search" name="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
</form>
<div id="searchresults-outer" class="searchresults-outer hidden">
<div id="searchresults-header" class="searchresults-header"></div>
<ul id="searchresults">
</ul>
</div>
</div>
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
<script type="text/javascript">
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
});
</script>
<div id="content" class="content">
<main>
<h1><a class="header" href="#mdbook" id="mdbook">mdBook</a></h1>
<p><strong>mdBook</strong> is a command line tool and Rust crate to create books using Markdown
files. It's very similar to Gitbook but written in
<a href="http://www.rust-lang.org">Rust</a>.</p>
<p>What you are reading serves as an example of the output of mdBook and at the
same time as a high-level documentation.</p>
<p>mdBook is free and open source, you can find the source code on
<a href="https://github.com/rust-lang/mdBook">GitHub</a>. Issues and feature
requests can be posted on the <a href="https://github.com/rust-lang/mdBook/issues">GitHub issue
tracker</a>.</p>
<h2><a class="header" href="#api-docs" id="api-docs">API docs</a></h2>
<p>Alongside this book you can also read the <a href="https://docs.rs/mdbook/*/mdbook/">API
docs</a> generated by Rustdoc if you would like
to use mdBook as a crate or write a new renderer and need a more low-level
overview.</p>
<h2><a class="header" href="#license" id="license">License</a></h2>
<p>mdBook, all the source code, is released under the <a href="https://www.mozilla.org/MPL/2.0/">Mozilla Public License
v2.0</a>.</p>
<h1><a class="header" href="#command-line-tool" id="command-line-tool">Command Line Tool</a></h1>
<p>mdBook can be used either as a command line tool or a <a href="https://crates.io/crates/mdbook">Rust
crate</a>. Let's focus on the command line tool
capabilities first.</p>
<h2><a class="header" href="#install-from-binaries" id="install-from-binaries">Install From Binaries</a></h2>
<p>Precompiled binaries are provided for major platforms on a best-effort basis.
Visit <a href="https://github.com/rust-lang/mdBook/releases">the releases page</a>
to download the appropriate version for your platform.</p>
<h2><a class="header" href="#install-from-source" id="install-from-source">Install From Source</a></h2>
<p>mdBook can also be installed from source</p>
<h3><a class="header" href="#pre-requisite" id="pre-requisite">Pre-requisite</a></h3>
<p>mdBook is written in <strong><a href="https://www.rust-lang.org/">Rust</a></strong> and therefore needs
to be compiled with <strong>Cargo</strong>. If you haven't already installed Rust, please go
ahead and <a href="https://www.rust-lang.org/tools/install">install it</a> now.</p>
<h3><a class="header" href="#install-cratesio-version" id="install-cratesio-version">Install Crates.io version</a></h3>
<p>Installing mdBook is relatively easy if you already have Rust and Cargo
installed. You just have to type this snippet in your terminal:</p>
<pre><code class="language-bash">cargo install mdbook
</code></pre>
<p>This will fetch the source code for the latest release from
<a href="https://crates.io/">Crates.io</a> and compile it. You will have to add Cargo's
<code>bin</code> directory to your <code>PATH</code>.</p>
<p>Run <code>mdbook help</code> in your terminal to verify if it works. Congratulations, you
have installed mdBook!</p>
<h3><a class="header" href="#install-git-version" id="install-git-version">Install Git version</a></h3>
<p>The <strong><a href="https://github.com/rust-lang/mdBook">git version</a></strong> contains all
the latest bug-fixes and features, that will be released in the next version on
<strong>Crates.io</strong>, if you can't wait until the next release. You can build the git
version yourself. Open your terminal and navigate to the directory of you
choice. We need to clone the git repository and then build it with Cargo.</p>
<pre><code class="language-bash">git clone --depth=1 https://github.com/rust-lang/mdBook.git
cd mdBook
cargo build --release
</code></pre>
<p>The executable <code>mdbook</code> will be in the <code>./target/release</code> folder, this should be
added to the path.</p>
<h1><a class="header" href="#the-init-command" id="the-init-command">The init command</a></h1>
<p>There is some minimal boilerplate that is the same for every new book. It's for
this purpose that mdBook includes an <code>init</code> command.</p>
<p>The <code>init</code> command is used like this:</p>
<pre><code class="language-bash">mdbook init
</code></pre>
<p>When using the <code>init</code> command for the first time, a couple of files will be set
up for you:</p>
<pre><code class="language-bash">book-test/
├── book
└── src
├── chapter_1.md
└── SUMMARY.md
</code></pre>
<ul>
<li>
<p>The <code>src</code> directory is where you write your book in markdown. It contains all
the source files, configuration files, etc.</p>
</li>
<li>
<p>The <code>book</code> directory is where your book is rendered. All the output is ready
to be uploaded to a server to be seen by your audience.</p>
</li>
<li>
<p>The <code>SUMMARY.md</code> file is the most important file, it's the skeleton of your
book and is discussed in more detail <a href="cli/../format/summary.html">in another
chapter</a></p>
</li>
</ul>
<h4><a class="header" href="#tip-generate-chapters-from-summarymd" id="tip-generate-chapters-from-summarymd">Tip: Generate chapters from SUMMARY.md</a></h4>
<p>When a <code>SUMMARY.md</code> file already exists, the <code>init</code> command will first parse it
and generate the missing files according to the paths used in the <code>SUMMARY.md</code>.
This allows you to think and create the whole structure of your book and then
let mdBook generate it for you.</p>
<h4><a class="header" href="#specify-a-directory" id="specify-a-directory">Specify a directory</a></h4>
<p>The <code>init</code> command can take a directory as an argument to use as the book's root
instead of the current working directory.</p>
<pre><code class="language-bash">mdbook init path/to/book
</code></pre>
<h4><a class="header" href="#--theme" id="--theme">--theme</a></h4>
<p>When you use the <code>--theme</code> flag, the default theme will be copied into a
directory called <code>theme</code> in your source directory so that you can modify it.</p>
<p>The theme is selectively overwritten, this means that if you don't want to
overwrite a specific file, just delete it and the default file will be used.</p>
<h1><a class="header" href="#the-build-command" id="the-build-command">The build command</a></h1>
<p>The build command is used to render your book:</p>
<pre><code class="language-bash">mdbook build
</code></pre>
<p>It will try to parse your <code>SUMMARY.md</code> file to understand the structure of your
book and fetch the corresponding files.</p>
<p>The rendered output will maintain the same directory structure as the source for
convenience. Large books will therefore remain structured when rendered.</p>
<h4><a class="header" href="#specify-a-directory-1" id="specify-a-directory-1">Specify a directory</a></h4>
<p>The <code>build</code> command can take a directory as an argument to use as the book's
root instead of the current working directory.</p>
<pre><code class="language-bash">mdbook build path/to/book
</code></pre>
<h4><a class="header" href="#--open" id="--open">--open</a></h4>
<p>When you use the <code>--open</code> (<code>-o</code>) flag, mdbook will open the rendered book in
your default web browser after building it.</p>
<h4><a class="header" href="#--dest-dir" id="--dest-dir">--dest-dir</a></h4>
<p>The <code>--dest-dir</code> (<code>-d</code>) option allows you to change the output directory for the
book. Relative paths are interpreted relative to the book's root directory. If
not specified it will default to the value of the <code>build.build-dir</code> key in
<code>book.toml</code>, or to <code>./book</code>.</p>
<hr />
<p><em><strong>Note:</strong></em> <em>The build command copies all files (excluding files with <code>.md</code> extension) from the source directory
into the build directory.</em></p>
<h1><a class="header" href="#the-watch-command" id="the-watch-command">The watch command</a></h1>
<p>The <code>watch</code> command is useful when you want your book to be rendered on every
file change. You could repeatedly issue <code>mdbook build</code> every time a file is
changed. But using <code>mdbook watch</code> once will watch your files and will trigger a
build automatically whenever you modify a file.</p>
<h4><a class="header" href="#specify-a-directory-2" id="specify-a-directory-2">Specify a directory</a></h4>
<p>The <code>watch</code> command can take a directory as an argument to use as the book's
root instead of the current working directory.</p>
<pre><code class="language-bash">mdbook watch path/to/book
</code></pre>
<h4><a class="header" href="#--open-1" id="--open-1">--open</a></h4>
<p>When you use the <code>--open</code> (<code>-o</code>) option, mdbook will open the rendered book in
your default web browser.</p>
<h4><a class="header" href="#--dest-dir-1" id="--dest-dir-1">--dest-dir</a></h4>
<p>The <code>--dest-dir</code> (<code>-d</code>) option allows you to change the output directory for the
book. Relative paths are interpreted relative to the book's root directory. If
not specified it will default to the value of the <code>build.build-dir</code> key in
<code>book.toml</code>, or to <code>./book</code>.</p>
<h1><a class="header" href="#the-serve-command" id="the-serve-command">The serve command</a></h1>
<p>The serve command is used to preview a book by serving it over HTTP at
<code>localhost:3000</code> by default. Additionally it watches the book's directory for
changes, rebuilding the book and refreshing clients for each change. A websocket
connection is used to trigger the client-side refresh.</p>
<p><em><strong>Note:</strong></em> <em>The <code>serve</code> command is for testing a book's HTML output, and is not
intended to be a complete HTTP server for a website.</em></p>
<h4><a class="header" href="#specify-a-directory-3" id="specify-a-directory-3">Specify a directory</a></h4>
<p>The <code>serve</code> command can take a directory as an argument to use as the book's
root instead of the current working directory.</p>
<pre><code class="language-bash">mdbook serve path/to/book
</code></pre>
<h4><a class="header" href="#server-options" id="server-options">Server options</a></h4>
<p><code>serve</code> has four options: the HTTP port, the WebSocket port, the HTTP hostname
to listen on, and the hostname for the browser to connect to for WebSockets.</p>
<p>For example: suppose you have an nginx server for SSL termination which has a
public address of 192.168.1.100 on port 80 and proxied that to 127.0.0.1 on port
8000. To run use the nginx proxy do:</p>
<pre><code class="language-bash">mdbook serve path/to/book -p 8000 -n 127.0.0.1 --websocket-hostname 192.168.1.100
</code></pre>
<p>If you were to want live reloading for this you would need to proxy the
websocket calls through nginx as well from <code>192.168.1.100:<WS_PORT></code> to
<code>127.0.0.1:<WS_PORT></code>. The <code>-w</code> flag allows for the websocket port to be
configured.</p>
<h4><a class="header" href="#--open-2" id="--open-2">--open</a></h4>
<p>When you use the <code>--open</code> (<code>-o</code>) flag, mdbook will open the book in your
default web browser after starting the server.</p>
<h4><a class="header" href="#--dest-dir-2" id="--dest-dir-2">--dest-dir</a></h4>
<p>The <code>--dest-dir</code> (<code>-d</code>) option allows you to change the output directory for the
book. Relative paths are interpreted relative to the book's root directory. If
not specified it will default to the value of the <code>build.build-dir</code> key in
<code>book.toml</code>, or to <code>./book</code>.</p>
<h1><a class="header" href="#the-test-command" id="the-test-command">The test command</a></h1>
<p>When writing a book, you sometimes need to automate some tests. For example,
<a href="https://doc.rust-lang.org/stable/book/">The Rust Programming Book</a> uses a lot
of code examples that could get outdated. Therefore it is very important for
them to be able to automatically test these code examples.</p>
<p>mdBook supports a <code>test</code> command that will run all available tests in a book. At
the moment, only rustdoc tests are supported, but this may be expanded upon in
the future.</p>
<h4><a class="header" href="#disable-tests-on-a-code-block" id="disable-tests-on-a-code-block">Disable tests on a code block</a></h4>
<p>rustdoc doesn't test code blocks which contain the <code>ignore</code> attribute:</p>
<pre><code>```rust,ignore
fn main() {}
```
</code></pre>
<p>rustdoc also doesn't test code blocks which specify a language other than Rust:</p>
<pre><code>```markdown
**Foo**: _bar_
```
</code></pre>
<p>rustdoc <em>does</em> test code blocks which have no language specified:</p>
<pre><code>```
This is going to cause an error!
```
</code></pre>
<h4><a class="header" href="#specify-a-directory-4" id="specify-a-directory-4">Specify a directory</a></h4>
<p>The <code>test</code> command can take a directory as an argument to use as the book's root
instead of the current working directory.</p>
<pre><code class="language-bash">mdbook test path/to/book
</code></pre>
<h4><a class="header" href="#--library-path" id="--library-path">--library-path</a></h4>
<p>The <code>--library-path</code> (<code>-L</code>) option allows you to add directories to the library
search path used by <code>rustdoc</code> when it builds and tests the examples. Multiple
directories can be specified with multiple options (<code>-L foo -L bar</code>) or with a
comma-delimited list (<code>-L foo,bar</code>).</p>
<h4><a class="header" href="#--dest-dir-3" id="--dest-dir-3">--dest-dir</a></h4>
<p>The <code>--dest-dir</code> (<code>-d</code>) option allows you to change the output directory for the
book. Relative paths are interpreted relative to the book's root directory. If
not specified it will default to the value of the <code>build.build-dir</code> key in
<code>book.toml</code>, or to <code>./book</code>.</p>
<h1><a class="header" href="#the-clean-command" id="the-clean-command">The clean command</a></h1>
<p>The clean command is used to delete the generated book and any other build
artifacts.</p>
<pre><code class="language-bash">mdbook clean
</code></pre>
<h4><a class="header" href="#specify-a-directory-5" id="specify-a-directory-5">Specify a directory</a></h4>
<p>The <code>clean</code> command can take a directory as an argument to use as the book's
root instead of the current working directory.</p>
<pre><code class="language-bash">mdbook clean path/to/book
</code></pre>
<h4><a class="header" href="#--dest-dir-4" id="--dest-dir-4">--dest-dir</a></h4>
<p>The <code>--dest-dir</code> (<code>-d</code>) option allows you to override the book's output
directory, which will be deleted by this command. Relative paths are interpreted
relative to the book's root directory. If not specified it will default to the
value of the <code>build.build-dir</code> key in <code>book.toml</code>, or to <code>./book</code>.</p>
<pre><code class="language-bash">mdbook clean --dest-dir=path/to/book
</code></pre>
<p><code>path/to/book</code> could be absolute or relative.</p>
<h1><a class="header" href="#format" id="format">Format</a></h1>
<p>In this section you will learn how to:</p>
<ul>
<li>Structure your book correctly</li>
<li>Format your <code>SUMMARY.md</code> file</li>
<li>Configure your book using <code>book.toml</code></li>
<li>Customize your theme</li>
</ul>
<h1><a class="header" href="#summarymd" id="summarymd">SUMMARY.md</a></h1>
<p>The summary file is used by mdBook to know what chapters to include, in what
order they should appear, what their hierarchy is and where the source files
are. Without this file, there is no book.</p>
<p>Even though <code>SUMMARY.md</code> is a markdown file, the formatting is very strict to
allow for easy parsing. Let's see how you should format your <code>SUMMARY.md</code> file.</p>
<h4><a class="header" href="#allowed-elements" id="allowed-elements">Allowed elements</a></h4>
<ol>
<li>
<p><em><strong>Title</strong></em> It's common practice to begin with a title, generally <code
class="language-markdown"># Summary</code>. But it is not mandatory, the
parser just ignores it. So you can too if you feel like it.</p>
</li>
<li>
<p><em><strong>Prefix Chapter</strong></em> Before the main numbered chapters you can add a couple
of elements that will not be numbered. This is useful for forewords,
introductions, etc. There are however some constraints. You can not nest
prefix chapters, they should all be on the root level. And you can not add
prefix chapters once you have added numbered chapters.</p>
<pre><code class="language-markdown">[Title of prefix element](relative/path/to/markdown.md)
</code></pre>
</li>
<li>
<p><em><strong>Numbered Chapter</strong></em> Numbered chapters are the main content of the book,
they will be numbered and can be nested, resulting in a nice hierarchy
(chapters, sub-chapters, etc.)</p>
<pre><code class="language-markdown">- [Title of the Chapter](relative/path/to/markdown.md)
</code></pre>
<p>You can either use <code>-</code> or <code>*</code> to indicate a numbered chapter.</p>
</li>
<li>
<p><em><strong>Suffix Chapter</strong></em> After the numbered chapters you can add a couple of
non-numbered chapters. They are the same as prefix chapters but come after
the numbered chapters instead of before.</p>
</li>
</ol>
<p>All other elements are unsupported and will be ignored at best or result in an
error.</p>
<h1><a class="header" href="#configuration" id="configuration">Configuration</a></h1>
<p>You can configure the parameters for your book in the <em><strong>book.toml</strong></em> file.</p>
<p>Here is an example of what a <em><strong>book.toml</strong></em> file might look like:</p>
<pre><code class="language-toml">[book]
title = "Example book"
author = "John Doe"
description = "The example book covers examples."
[build]
build-dir = "my-example-book"
create-missing = false
[preprocessor.index]
[preprocessor.links]
[output.html]
additional-css = ["custom.css"]
[output.html.search]
limit-results = 15
</code></pre>
<h2><a class="header" href="#supported-configuration-options" id="supported-configuration-options">Supported configuration options</a></h2>
<p>It is important to note that <strong>any</strong> relative path specified in the
configuration will always be taken relative from the root of the book where the
configuration file is located.</p>
<h3><a class="header" href="#general-metadata" id="general-metadata">General metadata</a></h3>
<p>This is general information about your book.</p>
<ul>
<li><strong>title:</strong> The title of the book</li>
<li><strong>authors:</strong> The author(s) of the book</li>
<li><strong>description:</strong> A description for the book, which is added as meta
information in the html <code><head></code> of each page</li>
<li><strong>src:</strong> By default, the source directory is found in the directory named
<code>src</code> directly under the root folder. But this is configurable with the <code>src</code>
key in the configuration file.</li>
<li><strong>language:</strong> The main language of the book, which is used as a language attribute <code><html lang="en"></code> for example.</li>
</ul>
<p><strong>book.toml</strong></p>
<pre><code class="language-toml">[book]
title = "Example book"
authors = ["John Doe", "Jane Doe"]
description = "The example book covers examples."
src = "my-src" # the source files will be found in `root/my-src` instead of `root/src`
language = "en"
</code></pre>
<h3><a class="header" href="#build-options" id="build-options">Build options</a></h3>
<p>This controls the build process of your book.</p>
<ul>
<li>
<p><strong>build-dir:</strong> The directory to put the rendered book in. By default this is
<code>book/</code> in the book's root directory.</p>
</li>
<li>
<p><strong>create-missing:</strong> By default, any missing files specified in <code>SUMMARY.md</code>
will be created when the book is built (i.e. <code>create-missing = true</code>). If this
is <code>false</code> then the build process will instead exit with an error if any files
do not exist.</p>
</li>
<li>
<p><strong>use-default-preprocessors:</strong> Disable the default preprocessors of (<code>links</code> &
<code>index</code>) by setting this option to <code>false</code>.</p>
<p>If you have the same, and/or other preprocessors declared via their table
of configuration, they will run instead.</p>
<ul>
<li>For clarity, with no preprocessor configuration, the default <code>links</code> and
<code>index</code> will run.</li>
<li>Setting <code>use-default-preprocessors = false</code> will disable these
default preprocessors from running.</li>
<li>Adding <code>[preprocessor.links]</code>, for example, will ensure, regardless of
<code>use-default-preprocessors</code> that <code>links</code> it will run.</li>
</ul>
</li>
</ul>
<h2><a class="header" href="#configuring-preprocessors" id="configuring-preprocessors">Configuring Preprocessors</a></h2>
<p>The following preprocessors are available and included by default:</p>
<ul>
<li><code>links</code>: Expand the <code>{{ #playpen }}</code>, <code>{{ #include }}</code>, and <code>{{ #rustdoc_include }}</code> handlebars
helpers in a chapter to include the contents of a file.</li>
<li><code>index</code>: Convert all chapter files named <code>README.md</code> into <code>index.md</code>. That is
to say, all <code>README.md</code> would be rendered to an index file <code>index.html</code> in the
rendered book.</li>
</ul>
<p><strong>book.toml</strong></p>
<pre><code class="language-toml">[build]
build-dir = "build"
create-missing = false
[preprocessor.links]
[preprocessor.index]
</code></pre>
<h3><a class="header" href="#custom-preprocessor-configuration" id="custom-preprocessor-configuration">Custom Preprocessor Configuration</a></h3>
<p>Like renderers, preprocessor will need to be given its own table (e.g.
<code>[preprocessor.mathjax]</code>). In the section, you may then pass extra
configuration to the preprocessor by adding key-value pairs to the table.</p>
<p>For example</p>
<pre><code class="language-toml">[preprocessor.links]
# set the renderers this preprocessor will run for
renderers = ["html"]
some_extra_feature = true
</code></pre>
<h4><a class="header" href="#locking-a-preprocessor-dependency-to-a-renderer" id="locking-a-preprocessor-dependency-to-a-renderer">Locking a Preprocessor dependency to a renderer</a></h4>
<p>You can explicitly specify that a preprocessor should run for a renderer by
binding the two together.</p>
<pre><code class="language-toml">[preprocessor.mathjax]
renderers = ["html"] # mathjax only makes sense with the HTML renderer
</code></pre>
<h3><a class="header" href="#provide-your-own-command" id="provide-your-own-command">Provide Your Own Command</a></h3>
<p>By default when you add a <code>[preprocessor.foo]</code> table to your <code>book.toml</code> file,
<code>mdbook</code> will try to invoke the <code>mdbook-foo</code> executable. If you want to use a
different program name or pass in command-line arguments, this behaviour can
be overridden by adding a <code>command</code> field.</p>
<pre><code class="language-toml">[preprocessor.random]
command = "python random.py"
</code></pre>
<h2><a class="header" href="#configuring-renderers" id="configuring-renderers">Configuring Renderers</a></h2>
<h3><a class="header" href="#html-renderer-options" id="html-renderer-options">HTML renderer options</a></h3>
<p>The HTML renderer has a couple of options as well. All the options for the
renderer need to be specified under the TOML table <code>[output.html]</code>.</p>
<p>The following configuration options are available:</p>
<ul>
<li><strong>theme:</strong> mdBook comes with a default theme and all the resource files needed
for it. But if this option is set, mdBook will selectively overwrite the theme
files with the ones found in the specified folder.</li>
<li><strong>default-theme:</strong> The theme color scheme to select by default in the
'Change Theme' dropdown. Defaults to <code>light</code>.</li>
<li><strong>preferred-dark-theme:</strong> The default dark theme. This theme will be used if
the browser requests the dark version of the site via the
<a href="https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme">'prefers-color-scheme'</a>
CSS media query. Defaults to the same theme as <code>default-theme</code>.</li>
<li><strong>curly-quotes:</strong> Convert straight quotes to curly quotes, except for those
that occur in code blocks and code spans. Defaults to <code>false</code>.</li>
<li><strong>mathjax-support:</strong> Adds support for <a href="format/mathjax.html">MathJax</a>. Defaults to
<code>false</code>.</li>
<li><strong>google-analytics:</strong> If you use Google Analytics, this option lets you enable
it by simply specifying your ID in the configuration file.</li>
<li><strong>additional-css:</strong> If you need to slightly change the appearance of your book
without overwriting the whole style, you can specify a set of stylesheets that
will be loaded after the default ones where you can surgically change the
style.</li>
<li><strong>additional-js:</strong> If you need to add some behaviour to your book without
removing the current behaviour, you can specify a set of JavaScript files that
will be loaded alongside the default one.</li>
<li><strong>no-section-label:</strong> mdBook by defaults adds section label in table of
contents column. For example, "1.", "2.1". Set this option to true to disable
those labels. Defaults to <code>false</code>.</li>
<li><strong>fold:</strong> A subtable for configuring sidebar section-folding behavior.</li>
<li><strong>playpen:</strong> A subtable for configuring various playpen settings.</li>
<li><strong>search:</strong> A subtable for configuring the in-browser search functionality.
mdBook must be compiled with the <code>search</code> feature enabled (on by default).</li>
<li><strong>git-repository-url:</strong> A url to the git repository for the book. If provided
an icon link will be output in the menu bar of the book.</li>
<li><strong>git-repository-icon:</strong> The FontAwesome icon class to use for the git
repository link. Defaults to <code>fa-github</code>.</li>
</ul>
<p>Available configuration options for the <code>[output.html.fold]</code> table:</p>
<ul>
<li><strong>enable:</strong> Enable section-folding. When off, all folds are open.
Defaults to <code>false</code>.</li>
<li><strong>level:</strong> The higher the more folded regions are open. When level is 0, all
folds are closed. Defaults to <code>0</code>.</li>
</ul>
<p>Available configuration options for the <code>[output.html.playpen]</code> table:</p>
<ul>
<li><strong>editable:</strong> Allow editing the source code. Defaults to <code>false</code>.</li>
<li><strong>copyable:</strong> Display the copy button on code snippets. Defaults to <code>true</code>.</li>
<li><strong>copy-js:</strong> Copy JavaScript files for the editor to the output directory.
Defaults to <code>true</code>.</li>
<li><strong>line-numbers</strong> Display line numbers on editable sections of code. Requires both <code>editable</code> and <code>copy-js</code> to be <code>true</code>. Defaults to <code>false</code>.</li>
</ul>
<p>Available configuration options for the <code>[output.html.search]</code> table:</p>
<ul>
<li><strong>enable:</strong> Enables the search feature. Defaults to <code>true</code>.</li>
<li><strong>limit-results:</strong> The maximum number of search results. Defaults to <code>30</code>.</li>
<li><strong>teaser-word-count:</strong> The number of words used for a search result teaser.
Defaults to <code>30</code>.</li>
<li><strong>use-boolean-and:</strong> Define the logical link between multiple search words. If
true, all search words must appear in each result. Defaults to <code>false</code>.</li>
<li><strong>boost-title:</strong> Boost factor for the search result score if a search word
appears in the header. Defaults to <code>2</code>.</li>
<li><strong>boost-hierarchy:</strong> Boost factor for the search result score if a search word
appears in the hierarchy. The hierarchy contains all titles of the parent
documents and all parent headings. Defaults to <code>1</code>.</li>
<li><strong>boost-paragraph:</strong> Boost factor for the search result score if a search word
appears in the text. Defaults to <code>1</code>.</li>
<li><strong>expand:</strong> True if search should match longer results e.g. search <code>micro</code>
should match <code>microwave</code>. Defaults to <code>true</code>.</li>
<li><strong>heading-split-level:</strong> Search results will link to a section of the document
which contains the result. Documents are split into sections by headings this
level or less. Defaults to <code>3</code>. (<code>### This is a level 3 heading</code>)</li>
<li><strong>copy-js:</strong> Copy JavaScript files for the search implementation to the output
directory. Defaults to <code>true</code>.</li>
</ul>
<p>This shows all available HTML output options in the <strong>book.toml</strong>:</p>
<pre><code class="language-toml">[book]
title = "Example book"
authors = ["John Doe", "Jane Doe"]
description = "The example book covers examples."
[output.html]
theme = "my-theme"
default-theme = "light"
preferred-dark-theme = "navy"
curly-quotes = true
mathjax-support = false
google-analytics = "123456"
additional-css = ["custom.css", "custom2.css"]
additional-js = ["custom.js"]
no-section-label = false
git-repository-url = "https://github.com/rust-lang/mdBook"
git-repository-icon = "fa-github"
[output.html.fold]
enable = false
level = 0
[output.html.playpen]
editable = false
copy-js = true
line-numbers = false
[output.html.search]
enable = true
limit-results = 30
teaser-word-count = 30
use-boolean-and = true
boost-title = 2
boost-hierarchy = 1
boost-paragraph = 1
expand = true
heading-split-level = 3
copy-js = true
</code></pre>
<h3><a class="header" href="#markdown-renderer" id="markdown-renderer">Markdown Renderer</a></h3>
<p>The Markdown renderer will run preprocessors and then output the resulting
Markdown. This is mostly useful for debugging preprocessors, especially in
conjunction with <code>mdbook test</code> to see the Markdown that <code>mdbook</code> is passing
to <code>rustdoc</code>.</p>
<p>The Markdown renderer is included with <code>mdbook</code> but disabled by default.
Enable it by adding an emtpy table to your <code>book.toml</code> as follows:</p>
<pre><code class="language-toml">[output.markdown]
</code></pre>
<p>There are no configuration options for the Markdown renderer at this time;
only whether it is enabled or disabled.</p>
<p>See <a href="format/config.html#configuring-preprocessors">the preprocessors documentation</a> for how to
specify which preprocessors should run before the Markdown renderer.</p>
<h3><a class="header" href="#custom-renderers" id="custom-renderers">Custom Renderers</a></h3>
<p>A custom renderer can be enabled by adding a <code>[output.foo]</code> table to your
<code>book.toml</code>. Similar to <a href="format/config.html#configuring-preprocessors">preprocessors</a> this will
instruct <code>mdbook</code> to pass a representation of the book to <code>mdbook-foo</code> for
rendering.</p>
<p>Custom renderers will have access to all configuration within their table
(i.e. anything under <code>[output.foo]</code>), and the command to be invoked can be
manually specified with the <code>command</code> field.</p>
<h2><a class="header" href="#environment-variables" id="environment-variables">Environment Variables</a></h2>
<p>All configuration values can be overridden from the command line by setting the
corresponding environment variable. Because many operating systems restrict
environment variables to be alphanumeric characters or <code>_</code>, the configuration
key needs to be formatted slightly differently to the normal <code>foo.bar.baz</code> form.</p>
<p>Variables starting with <code>MDBOOK_</code> are used for configuration. The key is created
by removing the <code>MDBOOK_</code> prefix and turning the resulting string into
<code>kebab-case</code>. Double underscores (<code>__</code>) separate nested keys, while a single
underscore (<code>_</code>) is replaced with a dash (<code>-</code>).</p>
<p>For example:</p>
<ul>
<li><code>MDBOOK_foo</code> -> <code>foo</code></li>
<li><code>MDBOOK_FOO</code> -> <code>foo</code></li>
<li><code>MDBOOK_FOO__BAR</code> -> <code>foo.bar</code></li>
<li><code>MDBOOK_FOO_BAR</code> -> <code>foo-bar</code></li>
<li><code>MDBOOK_FOO_bar__baz</code> -> <code>foo-bar.baz</code></li>
</ul>
<p>So by setting the <code>MDBOOK_BOOK__TITLE</code> environment variable you can override the
book's title without needing to touch your <code>book.toml</code>.</p>
<blockquote>
<p><strong>Note:</strong> To facilitate setting more complex config items, the value of an
environment variable is first parsed as JSON, falling back to a string if the
parse fails.</p>
<p>This means, if you so desired, you could override all book metadata when
building the book with something like</p>
<pre><code class="language-shell">$ export MDBOOK_BOOK="{'title': 'My Awesome Book', authors: ['Michael-F-Bryan']}"
$ mdbook build
</code></pre>
</blockquote>
<p>The latter case may be useful in situations where <code>mdbook</code> is invoked from a
script or CI, where it sometimes isn't possible to update the <code>book.toml</code> before
building.</p>
<h1><a class="header" href="#theme" id="theme">Theme</a></h1>
<p>The default renderer uses a <a href="http://handlebarsjs.com/">handlebars</a> template to
render your markdown files and comes with a default theme included in the mdBook
binary.</p>
<p>The theme is totally customizable, you can selectively replace every file from
the theme by your own by adding a <code>theme</code> directory next to <code>src</code> folder in your
project root. Create a new file with the name of the file you want to override
and now that file will be used instead of the default file.</p>
<p>Here are the files you can override:</p>
<ul>
<li><em><strong>index.hbs</strong></em> is the handlebars template.</li>
<li><em><strong>book.css</strong></em> is the style used in the output. If you want to change the
design of your book, this is probably the file you want to modify. Sometimes
in conjunction with <code>index.hbs</code> when you want to radically change the layout.</li>
<li><em><strong>book.js</strong></em> is mostly used to add client side functionality, like hiding /
un-hiding the sidebar, changing the theme, ...</li>
<li><em><strong>highlight.js</strong></em> is the JavaScript that is used to highlight code snippets,
you should not need to modify this.</li>
<li><em><strong>highlight.css</strong></em> is the theme used for the code highlighting</li>
<li><em><strong>favicon.png</strong></em> the favicon that will be used</li>
</ul>
<p>Generally, when you want to tweak the theme, you don't need to override all the
files. If you only need changes in the stylesheet, there is no point in
overriding all the other files. Because custom files take precedence over
built-in ones, they will not get updated with new fixes / features.</p>
<p><strong>Note:</strong> When you override a file, it is possible that you break some
functionality. Therefore I recommend to use the file from the default theme as
template and only add / modify what you need. You can copy the default theme
into your source directory automatically by using <code>mdbook init --theme</code> just
remove the files you don't want to override.</p>
<h1><a class="header" href="#indexhbs" id="indexhbs">index.hbs</a></h1>
<p><code>index.hbs</code> is the handlebars template that is used to render the book. The
markdown files are processed to html and then injected in that template.</p>
<p>If you want to change the layout or style of your book, chances are that you
will have to modify this template a little bit. Here is what you need to know.</p>
<h2><a class="header" href="#data" id="data">Data</a></h2>
<p>A lot of data is exposed to the handlebars template with the "context". In the
handlebars template you can access this information by using</p>
<pre><code class="language-handlebars">{{name_of_property}}
</code></pre>
<p>Here is a list of the properties that are exposed:</p>
<ul>
<li>
<p><em><strong>language</strong></em> Language of the book in the form <code>en</code>, as specified in <code>book.toml</code> (if not specified, defaults to <code>en</code>). To use in <code
class="language-html"><html lang="{{ language }}"></code> for example.</p>
</li>
<li>
<p><em><strong>title</strong></em> Title of the book, as specified in <code>book.toml</code></p>
</li>
<li>
<p><em><strong>chapter_title</strong></em> Title of the current chapter, as listed in <code>SUMMARY.md</code></p>
</li>
<li>
<p><em><strong>path</strong></em> Relative path to the original markdown file from the source
directory</p>
</li>
<li>
<p><em><strong>content</strong></em> This is the rendered markdown.</p>
</li>
<li>
<p><em><strong>path_to_root</strong></em> This is a path containing exclusively <code>../</code>'s that points
to the root of the book from the current file. Since the original directory
structure is maintained, it is useful to prepend relative links with this
<code>path_to_root</code>.</p>
</li>
<li>
<p><em><strong>chapters</strong></em> Is an array of dictionaries of the form</p>
<pre><code class="language-json">{"section": "1.2.1", "name": "name of this chapter", "path": "dir/markdown.md"}
</code></pre>
<p>containing all the chapters of the book. It is used for example to construct
the table of contents (sidebar).</p>
</li>
</ul>
<h2><a class="header" href="#handlebars-helpers" id="handlebars-helpers">Handlebars Helpers</a></h2>
<p>In addition to the properties you can access, there are some handlebars helpers
at your disposal.</p>
<h3><a class="header" href="#1-toc" id="1-toc">1. toc</a></h3>
<p>The toc helper is used like this</p>
<pre><code class="language-handlebars">{{#toc}}{{/toc}}
</code></pre>
<p>and outputs something that looks like this, depending on the structure of your
book</p>
<pre><code class="language-html"><ul class="chapter">
<li><a href="link/to/file.html">Some chapter</a></li>
<li>
<ul class="section">
<li><a href="link/to/other_file.html">Some other Chapter</a></li>
</ul>
</li>
</ul>
</code></pre>
<p>If you would like to make a toc with another structure, you have access to the
chapters property containing all the data. The only limitation at the moment
is that you would have to do it with JavaScript instead of with a handlebars
helper.</p>
<pre><code class="language-html"><script>
var chapters = {{chapters}};
// Processing here
</script>
</code></pre>
<h3><a class="header" href="#2-previous--next" id="2-previous--next">2. previous / next</a></h3>
<p>The previous and next helpers expose a <code>link</code> and <code>name</code> property to the
previous and next chapters.</p>
<p>They are used like this</p>
<pre><code class="language-handlebars">{{#previous}}
<a href="{{link}}" class="nav-chapters previous">
<i class="fa fa-angle-left"></i>
</a>
{{/previous}}
</code></pre>
<p>The inner html will only be rendered if the previous / next chapter exists.
Of course the inner html can be changed to your liking.</p>
<hr />
<p><em>If you would like other properties or helpers exposed, please <a href="https://github.com/rust-lang/mdBook/issues">create a new
issue</a></em></p>
<h1><a class="header" href="#syntax-highlighting" id="syntax-highlighting">Syntax Highlighting</a></h1>
<p>For syntax highlighting I use <a href="https://highlightjs.org">Highlight.js</a> with a
custom theme.</p>
<p>Automatic language detection has been turned off, so you will probably want to
specify the programming language you use like this</p>
<pre><code class="language-markdown">```rust
fn main() {
// Some code
}
```</code></pre>
<h2><a class="header" href="#custom-theme" id="custom-theme">Custom theme</a></h2>
<p>Like the rest of the theme, the files used for syntax highlighting can be
overridden with your own.</p>
<ul>
<li><em><strong>highlight.js</strong></em> normally you shouldn't have to overwrite this file, unless
you want to use a more recent version.</li>
<li><em><strong>highlight.css</strong></em> theme used by highlight.js for syntax highlighting.</li>
</ul>
<p>If you want to use another theme for <code>highlight.js</code> download it from their
website, or make it yourself, rename it to <code>highlight.css</code> and put it in
the <code>theme</code> folder of your book.</p>
<p>Now your theme will be used instead of the default theme.</p>
<h2><a class="header" href="#hiding-code-lines" id="hiding-code-lines">Hiding code lines</a></h2>
<p>There is a feature in mdBook that lets you hide code lines by prepending them
with a <code>#</code>.</p>
<pre><code class="language-bash"># fn main() {
let x = 5;
let y = 6;
println!("{}", x + y);
# }
</code></pre>
<p>Will render as</p>
<pre><pre class="playpen"><code class="language-rust"><span class="boring">fn main() {
</span> let x = 5;
let y = 7;
println!("{}", x + y);
<span class="boring">}
</span></code></pre></pre>
<p><strong>At the moment, this only works for code examples that are annotated with
<code>rust</code>. Because it would collide with semantics of some programming languages.
In the future, we want to make this configurable through the <code>book.toml</code> so that
everyone can benefit from it.</strong></p>
<h2><a class="header" href="#improve-default-theme" id="improve-default-theme">Improve default theme</a></h2>
<p>If you think the default theme doesn't look quite right for a specific language,
or could be improved. Feel free to <a href="https://github.com/rust-lang/mdBook/issues">submit a new
issue</a> explaining what you
have in mind and I will take a look at it.</p>
<p>You could also create a pull-request with the proposed improvements.</p>
<p>Overall the theme should be light and sober, without to many flashy colors.</p>
<h1><a class="header" href="#editor" id="editor">Editor</a></h1>
<p>In addition to providing runnable code playpens, mdBook optionally allows them
to be editable. In order to enable editable code blocks, the following needs to
be added to the <em><strong>book.toml</strong></em>:</p>
<pre><code class="language-toml">[output.html.playpen]
editable = true
</code></pre>
<p>To make a specific block available for editing, the attribute <code>editable</code> needs
to be added to it:</p>
<pre><code class="language-markdown">```rust,editable
fn main() {
let number = 5;
print!("{}", number);
}
```</code></pre>
<p>The above will result in this editable playpen:</p>
<pre><pre class="playpen"><code class="language-rust editable">fn main() {
let number = 5;
print!("{}", number);
}
</code></pre></pre>
<p>Note the new <code>Undo Changes</code> button in the editable playpens.</p>
<h2><a class="header" href="#customizing-the-editor" id="customizing-the-editor">Customizing the Editor</a></h2>
<p>By default, the editor is the <a href="https://ace.c9.io/">Ace</a> editor, but, if desired,
the functionality may be overriden by providing a different folder:</p>
<pre><code class="language-toml">[output.html.playpen]
editable = true
editor = "/path/to/editor"
</code></pre>
<p>Note that for the editor changes to function correctly, the <code>book.js</code> inside of
the <code>theme</code> folder will need to be overriden as it has some couplings with the
default Ace editor.</p>
<h1><a class="header" href="#mathjax-support" id="mathjax-support">MathJax Support</a></h1>
<p>mdBook has optional support for math equations through
<a href="https://www.mathjax.org/">MathJax</a>.</p>
<p>To enable MathJax, you need to add the <code>mathjax-support</code> key to your <code>book.toml</code>
under the <code>output.html</code> section.</p>
<pre><code class="language-toml">[output.html]
mathjax-support = true
</code></pre>
<blockquote>
<p><strong>Note:</strong> The usual delimiters MathJax uses are not yet supported. You can't
currently use <code>$$ ... $$</code> as delimiters and the <code>\[ ... \]</code> delimiters need an
extra backslash to work. Hopefully this limitation will be lifted soon.</p>
</blockquote>
<blockquote>
<p><strong>Note:</strong> When you use double backslashes in MathJax blocks (for example in
commands such as <code>\begin{cases} \frac 1 2 \\ \frac 3 4 \end{cases}</code>) you need
to add <em>two extra</em> backslashes (e.g., <code>\begin{cases} \frac 1 2 \\\\ \frac 3 4 \end{cases}</code>).</p>
</blockquote>
<h3><a class="header" href="#inline-equations" id="inline-equations">Inline equations</a></h3>
<p>Inline equations are delimited by <code>\\(</code> and <code>\\)</code>. So for example, to render the
following inline equation \( \int x dx = \frac{x^2}{2} + C \) you would write
the following:</p>
<pre><code>\\( \int x dx = \frac{x^2}{2} + C \\)
</code></pre>
<h3><a class="header" href="#block-equations" id="block-equations">Block equations</a></h3>
<p>Block equations are delimited by <code>\\[</code> and <code>\\]</code>. To render the following
equation</p>
<p>\[ \mu = \frac{1}{N} \sum_{i=0} x_i \]</p>
<p>you would write:</p>
<pre><code class="language-bash">\\[ \mu = \frac{1}{N} \sum_{i=0} x_i \\]
</code></pre>
<h1><a class="header" href="#mdbook-specific-markdown" id="mdbook-specific-markdown">mdBook-specific markdown</a></h1>
<h2><a class="header" href="#hiding-code-lines-1" id="hiding-code-lines-1">Hiding code lines</a></h2>
<p>There is a feature in mdBook that lets you hide code lines by prepending them
with a <code>#</code> <a href="https://doc.rust-lang.org/stable/rustdoc/documentation-tests.html#hiding-portions-of-the-example">in the same way that Rustdoc does</a>.</p>
<pre><code class="language-bash"># fn main() {
let x = 5;
let y = 6;
println!("{}", x + y);
# }
</code></pre>
<p>Will render as</p>
<pre><pre class="playpen"><code class="language-rust"><span class="boring">fn main() {
</span> let x = 5;
let y = 7;
println!("{}", x + y);
<span class="boring">}
</span></code></pre></pre>
<h2><a class="header" href="#including-files" id="including-files">Including files</a></h2>
<p>With the following syntax, you can include files into your book:</p>
<pre><code class="language-hbs">{{#include file.rs}}
</code></pre>
<p>The path to the file has to be relative from the current source file.</p>
<p>mdBook will interpret included files as markdown. Since the include command
is usually used for inserting code snippets and examples, you will often
wrap the command with <code>```</code> to display the file contents without
interpretting them.</p>
<pre><code class="language-hbs">```
{{#include file.rs}}
```
</code></pre>
<h2><a class="header" href="#including-portions-of-a-file" id="including-portions-of-a-file">Including portions of a file</a></h2>
<p>Often you only need a specific part of the file e.g. relevant lines for an
example. We support four different modes of partial includes:</p>
<pre><code class="language-hbs">{{#include file.rs:2}}
{{#include file.rs::10}}
{{#include file.rs:2:}}
{{#include file.rs:2:10}}
</code></pre>
<p>The first command only includes the second line from file <code>file.rs</code>. The second
command includes all lines up to line 10, i.e. the lines from 11 till the end of
the file are omitted. The third command includes all lines from line 2, i.e. the
first line is omitted. The last command includes the excerpt of <code>file.rs</code>
consisting of lines 2 to 10.</p>
<p>To avoid breaking your book when modifying included files, you can also
include a specific section using anchors instead of line numbers.
An anchor is a pair of matching lines. The line beginning an anchor must
match the regex "ANCHOR:\s*[\w_-]+" and similarly the ending line must match
the regex "ANCHOR_END:\s*[\w_-]+". This allows you to put anchors in
any kind of commented line.</p>
<p>Consider the following file to include:</p>
<pre><code class="language-rs">/* ANCHOR: all */