forked from markuadoc/markua-spec
-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathspec.html
More file actions
19914 lines (19141 loc) · 798 KB
/
spec.html
File metadata and controls
19914 lines (19141 loc) · 798 KB
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">
<head>
<meta charset="UTF-8">
<title>Markua Spec</title>
<style type="text/css">
body { font-family: Helvetica, arial, freesans, clean, sans-serif;
line-height: 1.4;
max-width: 48em;
margin: auto;
padding: 0 0.5em 4em;
color: #333333;
background-color: #ffffff;
font-size: 13pt;
}
div#TOC ul { list-style: none; }
h1 { font-size: 140%; font-weight: bold; border-top: 1px solid gray; padding-top: 0.5em; }
h2 { font-size: 120%; font-weight: bold; }
h3 { font-size: 110%; font-weight: bold; }
h4 { font-size: 100%; font-weight: bold; }
a.definition { font-weight: bold; }
span.space { position: relative; }
span.number:after { content: " " }
span.space:after {
content: "·";
position: absolute;
/* create a mark that indicates a space (trick from D. Greenspan) */
top: 0; bottom: 7px; left: 1px; right: 1px;
color: #aaaaaa;
}
div.example { overflow: hidden; }
p { text-align: justify; }
pre { padding: 0.5em; margin: 0.2em 0 0.5em; font-size: 88%; }
pre {
white-space: pre-wrap; /* css-3 */
white-space: -moz-pre-wrap; /* Mozilla, since 1999 */
white-space: -pre-wrap; /* Opera 4-6 */
white-space: -o-pre-wrap; /* Opera 7 */
word-wrap: break-word; /* Internet Explorer 5.5+ */
}
code { font-family: monospace; background-color: #d3e1e4; }
pre > code { background-color: transparent; }
.example { font-size: 0; /* hack to get width: 50% to work on inline-block */
padding-bottom: 6pt; }
.column pre { font-size: 11pt; padding: 2pt 6pt; }
div.examplenum { font-size: 11pt; text-align: left; margin-bottom: 10px; }
div.column { display: inline-block; width: 50%; vertical-align: top; }
div.example > div:nth-child(2) { clear:left; background-color: #d3e1e4; }
div.example > div:nth-child(3) { clear:right; background-color: #c9cace; }
#watermark {
position: fixed;
bottom: 0;
left: 0;
padding: 1em;
width: 100%;
font-size: 120%;
opacity: 0.7;
z-index: 99;
color: white;
}
#watermark a { color: white; }
a.dingus {
margin-left: 1em;
cursor: pointer;
line-height: 30px;
padding: 4px 7px;
color: #ffffff;
background-color: #33c3f0;
box-shadow: 2px 2px 2px rgba(0, 0, 0, .2);
border-color: #4fcaef;
border-bottom: 2px #2a9ec1 solid;
border-right: 2px #2a9ec1 solid;
}
a.footnoteRef > sup:before {
content: "[";
}
a.footnoteRef > sup:after {
content: "]";
}
a.footnoteRef > sup {
vertical-align: baseline;
font-size: 100%;
}
@media print {
@page {
size: auto;
margin: 1.2in 1.2in 1.2in 1.2in;
}
body {
margin: 0;
line-height: 1.2;
font-size: 10pt;
}
.column pre { font-size: 9pt; }
div.examplenum { font-size: 9pt; }
a.dingus { display: none; }
}
</style>
<script src="https://code.jquery.com/jquery-2.2.0.min.js"></script>
<script type="text/javascript">
$(document).ready(function() {
$("div.example").each(function(e) {
var t = $(this).find('code.language-markdown').text();
$(this).find('a.dingus').click(function(f) {
window.open('/dingus/?text=' +
encodeURIComponent(t.replace(/→/g,"\t")));
});
});
$("code.language-markdown").dblclick(function(e) { window.open('/dingus/?text=' +
encodeURIComponent($(this).text()));
});
});
</script>
</head>
<body>
<h1 class="title">Markua Spec</h1>
<div class="version">Version 0.30.14 (2022-04-27)</div>
<div class="authors">
<span class="author"><em>This formal specification of Markua was developed at Leanpub, is written by Peter Armstrong, is based on the CommonMark Spec by John MacFarlane, and is licensed under the Creative Commons license CC-BY-SA 4.0.</em><br/><br/><hr/><br/>NOTE: If you are a Leanpub author, there are two different versions of Markua used on Leanpub. The default version is Markua 0.10, which is documented in <a href="https://leanpub.com/markua/read">The Markua Manual</a>. This document specifies Markua 0.30, which is currently in beta on <a href="https://leanpub.com">Leanpub</a>.<br/><br/><hr/><br/></span>
</div>
<div class="license">
<a rel="license"
href="http://creativecommons.org/licenses/by-sa/4.0/"><img alt="Creative
Commons BY-SA" style="border-width: 0;"
src="https://i.creativecommons.org/l/by-sa/4.0/80x15.png"
/></a><br/><span style="display: none;"><span xmlns:dct="http://purl.org/dc/terms/"
href="http://purl.org/dc/dcmitype/Text" property="dct:title"
rel="dct:type">CommonMark Spec</span> by
<a xmlns:cc="http://creativecommons.org/ns#"
href="http://spec.commonmark.org" property="cc:attributionName"
rel="cc:attributionURL">John MacFarlane</a> is licensed under a
<a rel="license"
href="http://creativecommons.org/licenses/by-sa/4.0/">Creative
Commons Attribution-ShareAlike 4.0 International License</a>.</span>
</div>
<div id="watermark"></div>
<div id="TOC">
<ul>
<li><a href="#introduction"><span class="number">1</span>Introduction</a>
<ul>
<li><a href="#the-magical-typewriter-m-"><span class="number">1.1</span>The magical typewriter (M)</a></li>
<li><a href="#markua-markdown-for-books-and-courses-m-"><span class="number">1.2</span>Markua: Markdown for books and courses (M)</a></li>
<li><a href="#markua-s-five-key-additions-to-markdown-m-"><span class="number">1.3</span>Markua’s five key additions to Markdown (M)</a></li>
<li><a href="#markua-s-one-key-subtraction-from-markdown-raw-html-is-removed-m-"><span class="number">1.4</span>Markua’s one key subtraction from Markdown: raw HTML is removed (M)</a></li>
<li><a href="#how-to-write-a-novel-in-markua-m-"><span class="number">1.5</span>How to write a novel in Markua (M)</a></li>
<li><a href="#how-to-write-almost-any-book-in-markua-m-"><span class="number">1.6</span>How to write almost any book in Markua (M)</a></li>
<li><a href="#for-leanpub-authors-m-"><span class="number">1.7</span>For Leanpub authors (M)</a></li>
<li><a href="#origin-and-structure-of-this-document-m-"><span class="number">1.8</span>Origin and structure of this document (M)</a></li>
<li><a href="#about-the-html-output-m-"><span class="number">1.9</span>About the HTML output (M)</a></li>
<li><a href="#why-the-name-markua-m-"><span class="number">1.10</span>Why the name “Markua”? (M)</a></li>
<li><a href="#what-is-markdown-"><span class="number">1.11</span>What is Markdown?</a></li>
<li><a href="#why-is-a-spec-needed-"><span class="number">1.12</span>Why is a spec needed?</a></li>
<li><a href="#about-this-document"><span class="number">1.13</span>About this document</a></li>
</ul>
</li>
<li><a href="#preliminaries"><span class="number">2</span>Preliminaries</a>
<ul>
<li><a href="#characters-and-lines"><span class="number">2.1</span>Characters and lines</a></li>
<li><a href="#tabs"><span class="number">2.2</span>Tabs</a></li>
<li><a href="#insecure-characters"><span class="number">2.3</span>Insecure characters</a></li>
<li><a href="#backslash-escapes"><span class="number">2.4</span>Backslash escapes</a></li>
<li><a href="#entity-and-numeric-character-references"><span class="number">2.5</span>Entity and numeric character references</a></li>
<li><a href="#emoji-m-"><span class="number">2.6</span>Emoji (M)</a></li>
</ul>
</li>
<li><a href="#document-semantics-m-"><span class="number">3</span>Document semantics (M)</a>
<ul>
<li><a href="#how-headers-define-document-structure-m-"><span class="number">3.1</span>How headers define document structure (M)</a></li>
<li><a href="#attribute-lists-m-"><span class="number">3.2</span>Attribute lists (M)</a></li>
<li><a href="#directives-m-"><span class="number">3.3</span>Directives (M)</a></li>
<li><a href="#concatenating-manuscript-files-inserts-blank-lines-between-them-m-"><span class="number">3.4</span>Concatenating manuscript files inserts blank lines between them (M)</a></li>
</ul>
</li>
<li><a href="#document-settings-m-"><span class="number">4</span>Document settings (M)</a>
<ul>
<li><a href="#document-settings-which-apply-to-books-and-courses-m-"><span class="number">4.1</span>Document settings which apply to books and courses (M)</a></li>
<li><a href="#document-settings-which-apply-to-books-only-m-"><span class="number">4.2</span>Document settings which apply to books only (M)</a></li>
<li><a href="#document-settings-which-apply-to-courses-only-m-"><span class="number">4.3</span>Document settings which apply to courses only (M)</a></li>
<li><a href="#multiple-document-settings-hashes-are-permitted-m-"><span class="number">4.4</span>Multiple document settings hashes are permitted (M)</a></li>
</ul>
</li>
<li><a href="#resources-m-"><span class="number">5</span>Resources (M)</a>
<ul>
<li><a href="#resource-attributes-m-"><span class="number">5.1</span>Resource attributes (M)</a></li>
<li><a href="#common-resource-attributes-m-"><span class="number">5.2</span>Common resource attributes (M)</a></li>
<li><a href="#resource-titles-make-figures-m-"><span class="number">5.3</span>Resource titles make figures (M)</a></li>
<li><a href="#resource-alt-text-m-"><span class="number">5.4</span>Resource alt text (M)</a></li>
<li><a href="#resource-types-m-"><span class="number">5.5</span>Resource types (M)</a></li>
<li><a href="#resource-formats-m-"><span class="number">5.6</span>Resource formats (M)</a></li>
<li><a href="#resource-classes-m-"><span class="number">5.7</span>Resource classes (M)</a></li>
<li><a href="#resource-locations-m-"><span class="number">5.8</span>Resource locations (M)</a></li>
</ul>
</li>
<li><a href="#blocks-and-inlines"><span class="number">6</span>Blocks and inlines</a>
<ul>
<li><a href="#precedence"><span class="number">6.1</span>Precedence</a></li>
<li><a href="#container-blocks-and-leaf-blocks"><span class="number">6.2</span>Container blocks and leaf blocks</a></li>
</ul>
</li>
<li><a href="#leaf-blocks"><span class="number">7</span>Leaf blocks</a>
<ul>
<li><a href="#thematic-breaks"><span class="number">7.1</span>Thematic breaks</a></li>
<li><a href="#atx-headings"><span class="number">7.2</span>ATX headings</a></li>
<li><a href="#setext-headings"><span class="number">7.3</span>Setext headings</a></li>
<li><a href="#indented-code-blocks"><span class="number">7.4</span>Indented code blocks</a></li>
<li><a href="#fenced-code-blocks"><span class="number">7.5</span>Fenced code blocks</a></li>
<li><a href="#code-resources-m-"><span class="number">7.6</span>Code resources (M)</a></li>
<li><a href="#verbatim-resources-m-"><span class="number">7.7</span>Verbatim resources (M)</a></li>
<li><a href="#no-html-blocks-m-"><span class="number">7.8</span>No HTML blocks (M)</a></li>
<li><a href="#link-reference-definitions"><span class="number">7.9</span>Link reference definitions</a></li>
<li><a href="#paragraphs"><span class="number">7.10</span>Paragraphs</a></li>
<li><a href="#blank-lines"><span class="number">7.11</span>Blank lines</a></li>
<li><a href="#tables-gfm-"><span class="number">7.12</span>Tables (GFM)</a></li>
<li><a href="#table-resources-and-csv-format-tables-m-"><span class="number">7.13</span>Table resources and CSV-format tables (M)</a></li>
</ul>
</li>
<li><a href="#container-blocks"><span class="number">8</span>Container blocks</a>
<ul>
<li><a href="#block-quotes"><span class="number">8.1</span>Block quotes</a></li>
<li><a href="#block-quotes-with-curly-braces-m-"><span class="number">8.2</span>Block quotes with curly braces (M)</a></li>
<li><a href="#list-items"><span class="number">8.3</span>List items</a></li>
<li><a href="#lists"><span class="number">8.4</span>Lists</a></li>
<li><a href="#list-attributes-m-"><span class="number">8.5</span>List attributes (M)</a></li>
<li><a href="#definition-lists-m-"><span class="number">8.6</span>Definition lists (M)</a></li>
<li><a href="#asides-m-"><span class="number">8.7</span>Asides (M)</a></li>
<li><a href="#blurbs-m-"><span class="number">8.8</span>Blurbs (M)</a></li>
</ul>
</li>
<li><a href="#quizzes-and-exercises-m-"><span class="number">9</span>Quizzes and exercises (M)</a>
<ul>
<li><a href="#quiz-and-exercise-output-m-"><span class="number">9.1</span>Quiz and exercise output (M)</a></li>
<li><a href="#quiz-and-exercise-validation-m-"><span class="number">9.2</span>Quiz and exercise validation (M)</a></li>
<li><a href="#quiz-and-exercise-attributes-m-"><span class="number">9.3</span>Quiz and exercise attributes (M)</a></li>
<li><a href="#multiple-choice-questions-m-"><span class="number">9.4</span>Multiple choice questions (M)</a></li>
<li><a href="#multiple-selection-questions-m-"><span class="number">9.5</span>Multiple selection questions (M)</a></li>
<li><a href="#fill-in-the-blank-questions-m-"><span class="number">9.6</span>Fill in the blank questions (M)</a></li>
<li><a href="#written-questions-m-"><span class="number">9.7</span>Written questions (M)</a></li>
<li><a href="#hints-on-questions-m-"><span class="number">9.8</span>Hints on questions (M)</a></li>
<li><a href="#question-alternates-m-"><span class="number">9.9</span>Question alternates (M)</a></li>
</ul>
</li>
<li><a href="#inlines"><span class="number">10</span>Inlines</a>
<ul>
<li><a href="#code-spans"><span class="number">10.1</span>Code spans</a></li>
<li><a href="#emphasis-and-strong-emphasis"><span class="number">10.2</span>Emphasis and strong emphasis</a></li>
<li><a href="#links"><span class="number">10.3</span>Links</a></li>
<li><a href="#crosslinks-and-ids-m-"><span class="number">10.4</span>Crosslinks and ids (M)</a></li>
<li><a href="#smart-crosslinks-m-"><span class="number">10.5</span>Smart crosslinks (M)</a></li>
<li><a href="#images"><span class="number">10.6</span>Images</a></li>
<li><a href="#image-resource-attributes-m-"><span class="number">10.7</span>Image resource attributes (M)</a></li>
<li><a href="#inline-svg-images-m-"><span class="number">10.8</span>Inline SVG images (M)</a></li>
<li><a href="#image-locations-and-embedding-m-"><span class="number">10.9</span>Image locations and embedding (M)</a></li>
<li><a href="#video-resources-m-"><span class="number">10.10</span>Video resources (M)</a></li>
<li><a href="#iframe-resources-m-"><span class="number">10.11</span>IFrame resources (M)</a></li>
<li><a href="#audio-resources-m-"><span class="number">10.12</span>Audio resources (M)</a></li>
<li><a href="#math-resources-m-"><span class="number">10.13</span>Math resources (M)</a></li>
<li><a href="#autolinks"><span class="number">10.14</span>Autolinks</a></li>
<li><a href="#no-raw-html-m-"><span class="number">10.15</span>No raw HTML (M)</a></li>
<li><a href="#hard-line-breaks"><span class="number">10.16</span>Hard line breaks</a></li>
<li><a href="#soft-line-breaks"><span class="number">10.17</span>Soft line breaks</a></li>
<li><a href="#character-substitutions-m-"><span class="number">10.18</span>Character substitutions (M)</a></li>
<li><a href="#footnotes-and-endnotes-m-"><span class="number">10.19</span>Footnotes and endnotes (M)</a></li>
<li><a href="#underline-m-"><span class="number">10.20</span>Underline (M)</a></li>
<li><a href="#superscript-and-subscript-m-"><span class="number">10.21</span>Superscript and subscript (M)</a></li>
<li><a href="#strikethrough-gfm-"><span class="number">10.22</span>Strikethrough (GFM)</a></li>
<li><a href="#index-entries-m-"><span class="number">10.23</span>Index entries (M)</a></li>
<li><a href="#syntactic-sugar-list-m-"><span class="number">10.24</span>Syntactic sugar list (M)</a></li>
<li><a href="#textual-content"><span class="number">10.25</span>Textual content</a></li>
</ul>
</li>
<li><a href="#appendix-a-parsing-strategy">Appendix: A parsing strategy</a>
<ul>
<li><a href="#overview">Overview</a></li>
<li><a href="#phase-1-block-structure">Phase 1: block structure</a></li>
<li><a href="#phase-2-inline-structure">Phase 2: inline structure</a></li>
</ul>
</li>
</ul>
</div>
<h1 id="introduction" class="definition">
<span class="number">1</span>Introduction
</h1>
<div class="extension">
<h2 id="the-magical-typewriter-m-" class="definition">
<span class="number">1.1</span>The magical typewriter (M)
</h2>
<p>Imagine you owned a magical typewriter.</p>
<p>When you used this magical typewriter, you wrote with fewer distractions. You
didn’t just write faster, you wrote better.</p>
<p>With your magical typewriter, you never worried about layout. The book formatted
itself.</p>
<p>You could hit a key on your magical typewriter to create an ebook from your
manuscript with one click.</p>
<p>All ebook formats would be created, and they’d all look good. You’d have PDF for
computers, MOBI for Kindle, and EPUB for everywhere else. The book would look
great on phones.</p>
<p>With your magical typewriter, you could publish your book before it was even
done, and get feedback from readers all over the world. You could automatically
share book updates with them. You would press one key on your magical typewriter
to publish a new version, and all your readers would have it instantly.</p>
<p>With your magical typewriter, you could easily compare your current manuscript
to any other version of your manuscript that had ever existed.</p>
<p>If you decided to make a print book, you could press a key on your magical
typewriter to get a print-ready PDF. All you would need to do is add a cover.</p>
<p>If you wanted to work with a designer, you could press a different key to
generate InDesign. They could then use this as a starting point for producing a
beautiful print book.</p>
<p>Or, if you wanted to work with a publisher, you could press a different key to
get a Word document.</p>
<p>Your magical typewriter could even transform your completed book manuscript into
a course that anyone in the world could take. All you’d need to do is to
add some quizzes and exercises and then press a key for your magical typewriter
to publish an online course for you. The quizzes and exercises would mark
themselves, and students would get certificates based on how well they did.</p>
<p>With your magical typewriter, you’d only have to do one thing:</p>
<p>Write.</p>
<p>Wouldn’t it be great if such a magical typewriter existed?</p>
<p>It does. At <a href="https://leanpub.com">Leanpub</a>, we’re building it.</p>
<p>But there’s one requirement for this magical typewriter to exist: a simple,
coherent, open, free, plain text format for a book or course manuscript.</p>
<p>This simple format will be the basis for the magical typewriter.</p>
<p>This simple format is called Markua.</p>
<p>This is its specification.</p>
<h2 id="markua-markdown-for-books-and-courses-m-" class="definition">
<span class="number">1.2</span>Markua: Markdown for books and courses (M)
</h2>
<p>Markua, pronounced “mar-coo-ah”, is Markdown for books and courses.</p>
<p>Markua maps Markdown syntax to book concepts, and then adds some new syntax and
concepts of its own.</p>
<p>Markua documents can be automatically transformed into every popular type of
ebook format. The computer programs which do this transformation are called
Markua Processors. These programs understand both Markua syntax and how to
generate the various output formats. An example Markua Processor is Leanpub:
Leanpub can output PDF, EPUB, MOBI and HTML from the same Markua document,
and can even output print-ready PDFs and InDesign files from them as well.</p>
<p>Markua has been developed with extensive real-world testing and feedback.
Markua has been used by Leanpub authors for years, both to create books and
online courses.</p>
<p>Markua was started at Leanpub in 2014, and benefited from the years of lessons
that Leanpub had learned from Leanpub Flavoured Markdown (LFM). Markua is the
successor to LFM. We have been iterating on our Markua support for many years.</p>
</div>
<div class="extension">
<h2 id="markua-s-five-key-additions-to-markdown-m-" class="definition">
<span class="number">1.3</span>Markua’s five key additions to Markdown (M)
</h2>
<p>Markua’s five main additions to Markdown are the following:</p>
<ol>
<li>The mapping of <strong>Markdown headings (h1, h2, h3, etc.) to book structures</strong>
(chapters, sections, sub-sections, etc.), which provides the ability for
Markua Processors like Leanpub to produce an ebook from a Markua manuscript
with one click.</li>
<li>The <strong>unified resource syntax</strong>, which lets Markua handle audio, code,
iframe, math, verbatim and video resources in the same way that it does
images and tables, and which supports inline, local and web resource
locations.</li>
<li>The <strong>attribute list syntax</strong>, which lets Markua define properties for
resources using the same syntax that is used for other document elements,
such as part headings and index entries.</li>
<li>A comprehensive definition of <strong>document settings</strong>, so that authors can use
Markua to produce documents which are styled via global switches, rather than
by tedious micromanagement.</li>
<li>The mapping of book structures to <strong>online courses</strong>, and the creation of a
plain-text microformat for course <strong>quizzes and exercises</strong>, which supports
automated marking and automated production of everything which is required
for an online course.</li>
</ol>
<p>If you have written something (say blog posts or lecture notes) in Markdown, you
can use a Markua Processor, such as Leanpub, to turn them into an ebook or
course with one click. Then, as you go down the path of enhancing the manuscript
and adding things which only make sense in books or courses, this process will
feel like decorating, not converting.</p>
<p>The goal is for writers who are familiar with Markdown to feel that with Markua,
Markdown just grew an understanding of book and course concepts.</p>
</div>
<div class="extension">
<h2 id="markua-s-one-key-subtraction-from-markdown-raw-html-is-removed-m-" class="definition">
<span class="number">1.4</span>Markua’s one key subtraction from Markdown: raw HTML is removed (M)
</h2>
<p>Markua also has one key subtraction from Markdown: support for raw HTML, either
as inlines or blocks, is completely removed.</p>
<p>Markdown and CommonMark support raw HTML. Markua does not support raw HTML.</p>
<p>Instead, in Markua <strong>all raw HTML elements are removed</strong>.</p>
<p>This is true both for raw HTML which is inserted as leaf blocks, and raw HTML
which is inserted as inlines. Neither of these are supported by Markua.</p>
<p>In both cases, <strong>raw HTML must be completely removed by the Markua Processor.</strong></p>
<p>As a side effect of this, since HTML comments are HTML, authors can use HTML
comments (<code><!-- a comment --></code>) as comments in Markua: since these comments are
HTML, they will be completely removed from the output (along with any other
raw HTML tags).</p>
<p>Markua and Markdown have different use cases. Markdown is a better way to write
HTML; Markua is a better way to write a book or course.</p>
<p>HTML is just one possible output format of Markua, and other possible Markua
output formats (such as LaTeX and PDF) are not based on HTML. If HTML blocks
were supported, a Markua Processor would have to support parsing and
meaningfully outputting all of HTML syntax as well as all of Markua syntax.</p>
<p>Since Markdown’s only output format target is HTML, it might as well support
HTML blocks: generating HTML from HTML is as simple as passing the HTML through.
From an implementation perspective, Markdown gets inline HTML support for free.
This is not true in the case of Markua.</p>
<p>Note that besides raw HTML, Markua does not remove anything else from Markdown.
(As is discussed later, the Markua spec is written with the CommonMark spec as a
starting point, so that you can verify this for yourself.)</p>
</div>
<div class="extension">
<h2 id="how-to-write-a-novel-in-markua-m-" class="definition">
<span class="number">1.5</span>How to write a novel in Markua (M)
</h2>
<p>The Markua specification is long. However, if you’re an author, the amount you
need to learn to write in Markua is actually very short.</p>
<p>This example shows everything you need to know to write a novel in Markua:</p>
<hr />
<pre><code># Chapter One
This is a paragraph. You just write.
Blank lines separate paragraphs. This is *italic text*.
This is another paragraph. You can manually wrap your paragraphs
however you want. Single newlines function like single spaces by
default.
* * *
That was a thematic break, which is used as a "scene break" in a novel.
# Chapter Two
This is a paragraph in a new chapter.
</code></pre>
<hr />
<p>By the way, everything in the above example is identical in the following
Markdown dialects:</p>
<ul>
<li>Markua as specified in this document</li>
<li>Leanpub Flavoured Markdown as described in the
<a href="https://leanpub.com/lfm/read">Leanpub Flavoured Markdown (LFM) Manual</a></li>
<li>GitHub Flavored Markdown as specified in the GFM Spec</li>
<li>CommonMark as specified by John MacFarlane in the CommonMark Spec</li>
<li>Markdown as originally described by John Gruber</li>
</ul>
<p>In the simple case, Markua is just a mapping from Markdown concepts to book
concepts. This is deliberate.</p>
<h2 id="how-to-write-almost-any-book-in-markua-m-" class="definition">
<span class="number">1.6</span>How to write almost any book in Markua (M)
</h2>
<p>The longer example below shows everything you need to know to write almost any
type of book, such as a computer programming book, in Markua. This example also
serves as a tutorial which explains most of Markua’s important syntax in its
content. Some parts of this syntax are just standard Markdown or CommonMark
syntax, and other parts are Markua extensions.</p>
<pre><code># Paragraphs
This is a paragraph. You just write.
Blank lines separate paragraphs. This is *italic text* and **this is bold**.
This is another paragraph. You can manually wrap your paragraphs
however you want. Single newlines function like single spaces by
default.
* * *
That was a thematic break, which is used as a "scene break" in a novel.
# Lists
Here's a numbered list (called an "ordered list", even though all lists are
ordered):
1. foo
2. bar
3. baz
Here's a bulleted list (called an "unordered list", for irony):
* foo
* bar
* baz
You can even have definition lists!
term 1
: definition 1a
: definition 1b
term 2
: definition 2
# Tables
You can also use tables, which work best for numeric tabular data
involving a small number of columns containing small numbers:
| Central Bank | Rate |
|--------------|-----------|
| JPY | -0.10% |
| EUR | 0.00% |
| USD | 0.00% |
| CAD | 0.25% |
Note that definition lists are preferred to tables for most use cases,
since typing text in a table quickly gets annoying.
# Headings
Markua supports both of Markdown's heading styles.
The preferred style, called atx headers, has the following meaning in Markua:
```
{class: part}
# Part
This is a paragraph.
# Chapter
This is a paragraph.
## Section
This is a paragraph.
### Sub-section
This is a paragraph.
#### Sub-sub-section
This is a paragraph.
##### Sub-sub-sub-section
This is a paragraph.
###### Sub-sub-sub-sub-section
This is a paragraph.
```
Note the use of three backticks in the above example, to treat the Markua like
inline code (instead of actually like headers).
The other style of headers, called Setext headers, has the following headings:
```
{class: part}
Part
====
This is a paragraph.
Chapter
=======
This is a paragraph.
Section
-------
This is a paragraph.
```
Setext headers look nice, but only if you're only using chapters and sections.
If you want to add sub-sections (or lower), you'll be using atx headers for at
least some of your headers. My advice is to just use atx headers all the time.
(The `{class: part}` attribute list on a chapter header to make a part header
does actually work with Setext headers, but it's really ugly.)
Note that while it is confusing and ugly to mix and match using atx and Setext
headers for chapters and sections in the same document, you can do it. However,
please don't.
Finally, headers and their mapping to document structure concepts are discussed
later in the Document Structure section.
# Images
You can add images like this:
You can specify the alt text and figure title like this:
An example of the difference between alt text and a figure title is:
You can also set the alt text and/or the figure title in an attribute list:
{alt: "a red apple", title: "The Original Mac"}
Attribute lists are one of Markua's additions to Markdown, and are discussed
later in this specification.
If you wish, you can configure a Markua Processor to convert alt text into a
figure title if no separate figure title is provided. (A figure title is
just as accessible as alt text, so this is fine.) Document settings are
discussed next.
# Document Settings
Various document settings can be specified at the start of a Markua document to
affect the behavior of the Markua Processor. For example, you can set the
`alt-title` setting to `all` to make images use the alt text as the figure
title instead of as alt text:
```
{
alt-title: all
}
# Chapter One
This is an apple with a figure title but no alt text:
```
This gets you the terseness of inserting images as figures in LFM, in a general
way. Note that if the `alt-title` document setting is set to `text` (the
default) this behavior only happens for text-based resources like code samples.
If the `alt-title` is set to `none`, it never happens.
The generalization of the Markdown image syntax into resources, and the addition
of document settings, are two more of Markua's additions to Markdown. These are
also both discussed later in this specification.
One important type of resource in Markua is code samples, which is discussed
next.
# Code Samples
The image syntax is the inspiration for the syntax for external code samples:
Just like with images, you can also use an attribute list for the title:
{title: "Hello World in Ruby"}
Note that you can also specify the figure title as the alt text, as long as
the document setting of `alt-title` is not set to `none`:
You can also have inline code samples, which can only have a title using an
attribute list:
{title: "Hello World in Ruby"}
```ruby
puts "hello"
```
You can also include single lines of code like `puts "hello"` in paragraphs
using backticks.
# Other Stuff
Note that you can easily add math `d = v_i t + \frac{1}{2} a t^2`$ as well,
either inline in a paragraph or as a figure, using LaTeX math as the format.
> Blockquotes are really easy too.
> --Peter Armstrong, *Markua Spec*
Markua has lots of features not discussed in this example. Read the manual or
the rest of the spec!
</code></pre>
</div>
<div class="extension">
<h2 id="for-leanpub-authors-m-" class="definition">
<span class="number">1.7</span>For Leanpub authors (M)
</h2>
<p>There are three ways to write in plain text on Leanpub. These are their
user manuals:</p>
<ol>
<li><a href="https://leanpub.com/lfm/read">Leanpub Flavoured Markdown (LFM)</a>
(LFM was launched in 2011. It is now obsolete, and is on long-term support.)</li>
<li><a href="https://leanpub.com/markua/read">Markua 0.10</a> (this is the default for
books and courses on Leanpub)</li>
<li><a href="https://leanpub.com/markua030/read">Markua 0.30 Beta</a> (the user manual for
Markua 0.30 is not yet stable, so for now you’re better off reading this!)</li>
</ol>
<p>Not all features in the Markua spec are supported in the Markua 0.30 beta. If
you want a stable experience and user manual, you currently need to use
Leanpub’s Markua 0.10 support (which is the default choice for new books).
This is also true if you want to create courses. Leanpub’s Markua 0.30
implementation does not support courses yet. (Also, LFM has never supported
courses.)</p>
<p>Leanpub’s Markua 0.10 support is fully documented in its own <a href="https://leanpub.com/markua/read">user
manual</a>. Everything documented in that
manual should work as described, and our Markua 0.10 version will continue to be
supported for years to come.</p>
<p>Even though the Markua Spec is based on the CommonMark Spec, Leanpub’s current
Markua support is not based on CommonMark. Markua and CommonMark were both
launched in 2014, within a few months of each other. Leanpub’s Markua
implementation was based on its Ruby-based implementation of LFM, which dates
back to 2011.</p>
<p>If you are writing a new book or course on Leanpub, you should absolutely choose
Markua over LFM. If you are familiar with LFM, the following list of the top 10
differences between Markua and LFM may be useful:</p>
<ol>
<li>In LFM, parts are created with <code>-# Part</code>. In Markua, parts are created an
attribute list on an atx or Setext heading.</li>
<li>In LFM, there is a special syntax for inserting code samples:
<code><<[Optional Title](code/some_code_file.rb)</code>. In Markua, however, code
is just a resource, and the LFM syntax is not supported.</li>
<li>In LFM, to mark code as added or removed, the magic words were
<code>leanpub-start-insert</code>, <code>leanpub-end-insert</code>, <code>leanpub-start-delete</code> and
<code>leanpub-end-delete</code>. In Markua, the magic words are <code>markua-start-insert</code>,
<code>markua-end-insert</code>, <code>markua-start-delete</code> and <code>markua-end-delete</code>.</li>
<li>In LFM, there is a special syntax for inserting math: <code>{$$}...{/$$}</code>. This
looks nice to people who like LaTeX, and looks like nothing else in
Markdown. In Markua, however, math is just another resource, and that
LaTeX-inspired syntax for wrapping math resources is not supported.</li>
<li>In LFM, there are <code>G></code> “generic boxes”. In Markua, these are replaced with
blurbs (<code>B></code>).</li>
<li>LFM had the <code>C></code> syntax to center text, but we didn’t have the same effect on
generic boxes, and blurbs did not exist. In Markua, a <code>C></code> syntax is just
syntactic sugar for a centered blurb, for greater consistency. Because of
this, the blurb also gets the ability to be centered by adding a
<code>{class: center}</code> attribute.</li>
<li>LFM had <code>{rtl}</code> and <code>{ltr}</code> directives. These are not supported in Markua,
and neither is a <code>{dir}</code> attribute in general: any given language is either a
left-to-right or a right-to-left language, so specifying the language with
the <code>lang</code> document setting and the <code>{lang: ___}</code> directive is sufficient.</li>
<li>LFM used Sample.txt to define the sample content. Markua moves the definition
of what constitutes sample content into a <code>{sample: true}</code> attribute on
parts, chapters and sections. So, in Markua, inclusion in the sample is at
the content level, not the file level. This helps avoid a number of bugs that
could happen with including at the file level, if a file did not clearly
break at a chapter boundary. (So, in Leanpub, the Sample.txt approach is not
supported for books which use Markua.)</li>
<li>LFM used Book.txt to define the book content. In Markua, the way that the
list of manuscript files is defined is considered out of scope of the Markua
specification itself. (Leanpub still uses the Book.txt approach to specify
which files are in a book, but other Markua Processors could use other
approaches, or could just support parsing single files or input streams.)</li>
<li>Most importantly, a number of features (courses, index entries, smart
crosslinks, etc.) exist in Markua and do not exist in LFM.</li>
</ol>
</div>
<div class="extension">
<h2 id="origin-and-structure-of-this-document-m-" class="definition">
<span class="number">1.8</span>Origin and structure of this document (M)
</h2>
<p>This is the Markua Spec, written by
<a href="https://twitter.com/peterarmstrong">Peter Armstrong</a>.</p>
<p>The Markua Spec is based on the CommonMark Spec, whose author is
<a href="https://johnmacfarlane.net/">John MacFarlane</a>.</p>
<p>This document also incorporates the specification of two of the five GitHub
Flavored Markdown (GFM) extensions from the <a href="https://github.github.com/gfm/">GFM
Spec</a>.</p>
<p>Like the CommonMark Spec and the GFM Spec, the Markua Spec is licensed under
the Creative Commons license
<a href="http://creativecommons.org/licenses/by-sa/4.0/">CC-BY-SA 4.0</a>.</p>
<p>This document has two types of intended readers:</p>
<ol>
<li>authors with advanced questions about Markua syntax</li>
<li>developers implementing Markua Processors</li>
</ol>
<p>The Markua Spec is a strange hybrid of the CommonMark Spec, the GFM Spec and the
specification of the Markua extensions.</p>
<p>The starting point is the CommonMark Spec. With the exception of the removal of
the HTML Blocks and Raw HTML sections, the entire CommonMark Spec is preserved
unchanged.</p>
<p>Next, two of the five GFM extensions are added. These are discussed
<a href="#github-flavored-markdown-gfm-extension-status-m-">below</a>.</p>
<p>Finally, many new chapters or sections about Markua are added. These are all
labeled with “(Markua extension)”.</p>
<p>So, for any given chapter or section of this document, it is either:</p>
<ol>
<li>written by John MacFarlane about CommonMark</li>
<li>written by GitHub employees about GFM, and ending with “(GFM)”</li>
<li>written by Peter Armstrong about Markua, and ending with “(M)”</li>
</ol>
<p>To be clear: every chapter or section which does not end with (M) or (GFM) is
from the original CommonMark Spec, and was written by John MacFarlane.</p>
<p>Together, these sections combine to specify Markua, since Markua is CommonMark,
minus HTML blocks and Raw HTML, plus two GFM extensions, plus many Markua
extensions.</p>
<p>While this hybrid approach of creating the Markua specification is somewhat odd,
it has a number of significant benefits:</p>
<ol>
<li>The CommonMark Spec is very good, and is licensed under the Creative Commons
license CC-BY-SA 4.0. Not starting with the CommonMark Spec would be an
exercise in vanity.</li>
<li>The CommonMark Spec is the defacto standard specification of Markdown. Any
specification not based on CommonMark will need to be compared to CommonMark,
so the most helpful thing to do is to just start with CommonMark.</li>
<li>Writing this specification as a series of extensions to CommonMark will
enable people who are implementing it to just start with a compliant
CommonMark implementation and modify it appropriately.</li>
<li>Defining all Markua changes as extensions to CommonMark or deletions from
CommonMark makes it abundantly clear whether something that Markua does
originates in CommonMark, or whether it was added by GFM or by Markua. This
is potentially helpful for authors, since it will show them what will work
in other Markdown dialects, and what won’t.</li>
<li>It means that updating this document to keep it current with the CommonMark
and GFM specs will be very easy.</li>
</ol>
<p>In terms of the GFM extensions, the following two GFM extensions are included
in the Markua Spec:</p>
<ol>
<li><a href="#tables-gfm-">Tables (GFM)</a></li>
<li><a href="#strikethrough-gfm-">Strikethrough (GFM)</a></li>
</ol>
<p>Their content is unchanged, but their titles are renamed to say “(GFM
extension)” instead of “(extension)”, to more clearly specify their provenance.</p>
<p>The other three GFM extensions are omitted:</p>
<ol>
<li><a href="https://github.github.com/gfm/#task-list-items-extension-">Task list items</a>
is omitted since Markua is for books and courses, not task lists.</li>
<li><a href="https://github.github.com/gfm/#disallowed-raw-html-extension-">Disallowed Raw HTML</a>
is omitted since Markua goes farther and <strong>completely removes all raw HTML</strong>,
both HTML added as HTML blocks or as raw HTML inlines.</li>
<li><a href="https://github.github.com/gfm/#autolinks-extension-">Autolinks</a> is omitted,
because the extra work to create a link is literally typing two characters
(<code><</code> and <code>></code>), so the added complexity both in parsing and in documentation
is not worth it. (It does make sense for, say, a discussion forum. It does
not make sense for books and courses.)</li>
</ol>
</div>
<div class="extension">
<h2 id="about-the-html-output-m-" class="definition">
<span class="number">1.9</span>About the HTML output (M)
</h2>
<p>The HTML mapping defined in this specification is NOT a complete specification
of the HTML documents produced by Markua Processors.</p>
<p>Also, the HTML mapping defined in the specification is NOT considered to be
canonical.</p>
<p>For example, consider the following Markua:</p>
<pre><code>
</code></pre>
<p>A Markua Processor can produce HTML that looks like this:</p>
<pre><code><p><img src="mac.jpg" alt="a red apple" title="The Original Mac" /></p>
</code></pre>
<p>(That is what was produced at <a href="https://spec.commonmark.org/dingus/">https://spec.commonmark.org/dingus/</a> on
2020-05-27, for example, and it is valid Markua as well as valid CommonMark.)</p>
<p>A Markua Processor can also, however, produce HTML that looks like this:</p>
<pre><code><p>
<figure>
<img src="mac.jpg"
alt="a red apple">
<figcaption>The Original Mac</figcaption>
</figure>
</p>
</code></pre>
<p>Both approaches are completely legitimate, and have pros and cons.</p>
<p>So, why show any HTML at all? There are two reasons:</p>
<ol>
<li>The CommonMark Spec shows HTML, and the Markua Spec tries to only be additive
to the CommonMark Spec.</li>
<li>Showing HTML helps Markua Processors to test their parsers.</li>
</ol>
<p>Finally, besides not being canonical, the HTML is not complete. It is only a
specification of the parts of the HTML mapping where there is less need to have
flexibility on the part of the Markua Processor.</p>
<p>The HTML mapping should be thought of specifying HTML fragments, not HTML
documents. In all of the examples, a Markua Processor may add more HTML before
and after the relevant content, as well as changing the relevant content itself.</p>
<p>If a Markua Processor wishes to test that it produces the correct HTML, it
should test that the HTML produced contains the specified output, not that it
is identical to the specified output.</p>
<p>Every example uses the default Markua document settings, unless otherwise
specified. Any custom settings are specified in a document settings list in the
top of the example.</p>
</div>
<div class="extension">
<h2 id="why-the-name-markua-m-" class="definition">
<span class="number">1.10</span>Why the name “Markua”? (M)
</h2>
<p>When I set out to specify Markua, I realized I needed a name. I wanted a name
that conveyed the love that I have for Markdown while not implying endorsement
by John Gruber in any way. I also did not want a name which referenced Leanpub:
Markua is a standalone specification with its own identity, which anyone
(including Leanpub competitors) can freely implement. Finally, I was on vacation
in Hawaii when I named Markua, and I wanted something that sounded happy,
friendly and almost Hawaiian. (Yes, I’m aware that there is no r in Hawaiian.)
I also wanted a name that had its .com domain name available, and that was short
and spellable, for branding purposes. The Markua name had all these properties.</p>
<p>So, I named it Markua, registered the domain name, and filed a trademark.
Markua and the Markua logo is a registered trademark of Ruboss Technology
Corporation, the company which created, owns and operates Leanpub.</p>
</div>
<h2 id="what-is-markdown-" class="definition">
<span class="number">1.11</span>What is Markdown?
</h2>
<p>Markdown is a plain text format for writing structured documents,
based on conventions for indicating formatting in email
and usenet posts. It was developed by John Gruber (with
help from Aaron Swartz) and released in 2004 in the form of a
<a href="http://daringfireball.net/projects/markdown/syntax">syntax description</a>
and a Perl script (<code>Markdown.pl</code>) for converting Markdown to
HTML. In the next decade, dozens of implementations were
developed in many languages. Some extended the original
Markdown syntax with conventions for footnotes, tables, and
other document elements. Some allowed Markdown documents to be
rendered in formats other than HTML. Websites like Reddit,
StackOverflow, and GitHub had millions of people using Markdown.
And Markdown started to be used beyond the web, to author books,
articles, slide shows, letters, and lecture notes.</p>
<p>What distinguishes Markdown from many other lightweight markup
syntaxes, which are often easier to write, is its readability.
As Gruber writes:</p>
<blockquote>
<p>The overriding design goal for Markdown’s formatting syntax is
to make it as readable as possible. The idea is that a
Markdown-formatted document should be publishable as-is, as
plain text, without looking like it’s been marked up with tags
or formatting instructions.
(<a href="http://daringfireball.net/projects/markdown/">http://daringfireball.net/projects/markdown/</a>)</p>
</blockquote>
<p>The point can be illustrated by comparing a sample of
<a href="http://www.methods.co.nz/asciidoc/">AsciiDoc</a> with
an equivalent sample of Markdown. Here is a sample of
AsciiDoc from the AsciiDoc manual:</p>
<pre><code>1. List item one.
+
List item one continued with a second paragraph followed by an
Indented block.
+
.................
$ ls *.sh
$ mv *.sh ~/tmp
.................
+
List item continued with a third paragraph.
2. List item two continued with an open block.
+
--
This paragraph is part of the preceding list item.
a. This list is nested and does not require explicit item
continuation.
+
This paragraph is part of the preceding list item.
b. List item b.
This paragraph belongs to item two of the outer list.
--
</code></pre>
<p>And here is the equivalent in Markdown:</p>
<pre><code>1. List item one.
List item one continued with a second paragraph followed by an
Indented block.
$ ls *.sh
$ mv *.sh ~/tmp
List item continued with a third paragraph.
2. List item two continued with an open block.
This paragraph is part of the preceding list item.
1. This list is nested and does not require explicit item continuation.
This paragraph is part of the preceding list item.
2. List item b.
This paragraph belongs to item two of the outer list.
</code></pre>
<p>The AsciiDoc version is, arguably, easier to write. You don’t need
to worry about indentation. But the Markdown version is much easier
to read. The nesting of list items is apparent to the eye in the
source, not just in the processed document.</p>
<h2 id="why-is-a-spec-needed-" class="definition">
<span class="number">1.12</span>Why is a spec needed?
</h2>
<p>John Gruber’s <a href="http://daringfireball.net/projects/markdown/syntax">canonical description of Markdown’s
syntax</a>
does not specify the syntax unambiguously. Here are some examples of
questions it does not answer:</p>
<ol>
<li>
<p>How much indentation is needed for a sublist? The spec says that
continuation paragraphs need to be indented four spaces, but is
not fully explicit about sublists. It is natural to think that
they, too, must be indented four spaces, but <code>Markdown.pl</code> does
not require that. This is hardly a “corner case,” and divergences
between implementations on this issue often lead to surprises for
users in real documents. (See <a href="https://web.archive.org/web/20170611172104/http://article.gmane.org/gmane.text.markdown.general/1997">this comment by John
Gruber</a>.)</p>
</li>
<li>
<p>Is a blank line needed before a block quote or heading?
Most implementations do not require the blank line. However,