forked from commonmark/commonmark-spec
-
Notifications
You must be signed in to change notification settings - Fork 10
/
spec.txt
17881 lines (13331 loc) · 467 KB
/
spec.txt
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
---
title: Markua Spec
author: '*This formal specification of Markua was developed at [Leanpub](https://leanpub.com), is written by Peter Armstrong, is based on the CommonMark Spec (version 0.31.2) by John MacFarlane, and is licensed under the Creative Commons license CC-BY-SA 4.0.*<br/><br/><hr/><br/>NOTE: If you are a Leanpub author, there are two different versions of Markua used on Leanpub. <strong>The default version of Markua for books on Leanpub is Markua 0.30, which is documented in this specification, and which is currently in beta on Leanpub.</strong> The default version of Markua for courses on Leanpub is still Markua 0.10, which is documented in [The Markua Manual](https://leanpub.com/markua/read). (You can still use Markua 0.10 and Leanpub Flavoured Markdown for books on Leanpub, of course.)<br/><br/><hr/><br/>'
version: '0.31.36'
date: '2024-04-30'
license: '[CC-BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/)'
...
# Introduction
<div class="extension">
## The magical typewriter (M)
Imagine you owned a magical typewriter.
When you used this magical typewriter, you wrote with fewer distractions. You
didn't just write faster, you wrote better.
With your magical typewriter, you never worried about layout. The book formatted
itself.
You could hit a key on your magical typewriter to create an ebook from your
manuscript with one click.
All ebook formats would be created, and they'd all look good. You'd have PDF for
computers, and EPUB for everywhere else. The book would look great on phones.
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.
With your magical typewriter, you could easily compare your current manuscript
to any other version of your manuscript that had ever existed.
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.
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.
Or, if you wanted to work with a publisher, you could press a different key to
get a Word document.
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.
With your magical typewriter, you'd only have to do one thing:
Write.
Wouldn't it be great if such a magical typewriter existed?
It does. At [Leanpub](https://leanpub.com), we're building it.
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.
This simple format will be the basis for the magical typewriter.
This simple format is called Markua.
This is its specification.
## Markua: Markdown for books and courses (M)
Markua, pronounced "mar-coo-ah", is Markdown for books and courses.
Markua maps Markdown syntax to book concepts, and then adds some new syntax and
concepts of its own.
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 and HTML from the same Markua document, and can
even output print-ready PDFs and InDesign files from them as well.
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.
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.
</div>
<div class="extension">
## Markua's five key additions to Markdown (M)
Markua's five main additions to Markdown are the following:
1. The mapping of **Markdown headings (h1, h2, h3, etc.) to book structures**
(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.
2. The **unified resource syntax**, 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.
3. The **attribute list syntax**, 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.
4. A comprehensive definition of **document settings**, so that authors can use
Markua to produce documents which are styled via global switches, rather than
by tedious micromanagement.
5. The mapping of book structures to **online courses**, and the creation of a
plain-text microformat for course **quizzes and exercises**, which supports
automated marking and automated production of everything which is required
for an online course.
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.
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.
</div>
<div class="extension">
## Markua's one key subtraction from Markdown: raw HTML is removed (M)
Markua also has one key subtraction from Markdown: support for raw HTML, either
as inlines or blocks, is completely removed.
Markdown and CommonMark support raw HTML. Markua does not support raw HTML.
Instead, in Markua **all raw HTML elements are removed**.
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.
In both cases, **raw HTML must be completely removed by the Markua Processor.**
As a side effect of this, since HTML comments are HTML, authors can use HTML
comments (`<!-- a comment -->`) as comments in Markua: since these comments are
HTML, they will be completely removed from the output (along with any other
raw HTML tags).
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.
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.
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.
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.)
</div>
<div class="extension">
## How to write a novel in Markua (M)
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.
This example shows everything you need to know to write a novel in Markua:
* * *
~~~
# 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.
~~~
* * *
By the way, everything in the above example is identical in the following
Markdown dialects:
* Markua as specified in this document
* Leanpub Flavoured Markdown as described in the
[Leanpub Flavoured Markdown (LFM) Manual](https://leanpub.com/lfm/read)
* GitHub Flavored Markdown as specified in the GFM Spec
* CommonMark as specified by John MacFarlane in the CommonMark Spec
* Markdown as originally described by John Gruber
In the simple case, Markua is just a mapping from Markdown concepts to book
concepts. This is deliberate.
## How to write almost any book in Markua (M)
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.
~~~
# 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:
![](mac.jpg)
You can specify the alt text and figure title like this:
![alt text for accessibility](image.png "Figure Title")
An example of the difference between alt text and a figure title is:
![a red apple](mac.jpg "The Original Mac")
You can also set the alt text and/or the figure title in an attribute list:
{alt: "a red apple", title: "The Original Mac"}
![](mac.jpg)
Attribute lists are one of Markua's additions to Markdown, and are discussed
later in this specification.
Finally, you can set an image figure title using the alt text, if the
`alt-title` document setting is set to `all`:
![The Original Mac](mac.jpg)
The default value of `alt-title` is `all`, which means that all resources
can have their title specified in the alt text. There is also a value of
`text`, which means that only text-based resources like code can have their
title specified in the alt text. Finally, there is a value of `none`, which
means that no resources can have their title specified in the alt text. The
`alt-title` document setting is discussed
[in great detail here](#the-alt-title-document-setting-m-).
# 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, if you want single
newlines to insert a forced line break in the PDF, EPUB and HTML output formats
(instead of the single space that results by default), set the `soft-breaks`
document setting to `break` instead of the default of `space`:
```
{
soft-breaks: break
}
# Chapter One
This will be on a line
and this will be on the next line.
```
This `soft-breaks` setting is so important it is discussed in its own
section below.
# Code Samples
The generalization of the Markdown image syntax into resources is one of
Markua's most important additions to Markdown. For example, the image syntax
is the inspiration for the syntax for external code samples:
![](hello.rb "Hello World in Ruby")
Just like with images, you can also use an attribute list for the title:
{title: "Hello World in Ruby"}
![](hello.rb)
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`:
![Hello World in Ruby](hello.rb)
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!
~~~
</div>
<div class="extension">
## For Leanpub authors (M)
There are three ways to write in plain text on Leanpub. These are their
user manuals:
1. [Leanpub Flavoured Markdown (LFM)](https://leanpub.com/lfm/read) - LFM was
launched in 2011, and evolved until 2013. It is now obsolete, and is on
long-term support.
2. [Markua 0.10](https://leanpub.com/markua/read) - Markua 0.10 was launched in
2014, and evolved until 2021. It is currently the only way to write courses
on Leanpub.
3. [Markua 0.30 Beta](https://leanpub.com/markua030/read) - The Markua 0.30
beta was launched on Leanpub in 2021. Currently, Markua 0.30 is the default
for new books on Leanpub. The user manual for Markua 0.30 is not yet stable,
so for now you're much better off reading this spec!
Not all features in the Markua spec are supported in the Markua 0.30 beta.
However, the Markua 0.30 beta is good enough that it is the default choice for
new Leanpub books!
You can still choose to use Leanpub's Markua 0.10 support, of course. This is
also true if you want to create courses. Leanpub's Markua 0.30 implementation
does not support courses yet.
You can also choose to use LFM, but unless you're dealing with a legacy Leanpub
book, there's no good reason to do so. You're much better off using the
Markua 0.30 beta than LFM.
Markua 0.30 is compared to LFM and Markua 0.10 in the next sections below.
These sections are primarily here for the benefit of Leanpub authors, but also
to show the origin of how Markua 0.30 evolved.
</div>
<div class="extension">
## Markua 0.30 vs. Leanpub Flavoured Markdown (LFM) (M)
If you have used Leanpub Flavoured Markdown (LFM) in the past, you may be
curious about the main differences between Markua 0.30 and LFM.
First, to emphasize the most obvious point: **If you are writing a new book or
course on Leanpub, you should absolutely choose Markua over LFM.** For new
books, you should choose Markua 0.30. For new courses, you should choose Markua
0.10 for now, since we do not support Markua 0.30 for courses yet.
**There is no good reason to start any new project using LFM.** The only reason
we continue to support LFM on Leanpub is for updates to legacy books.
There are many differences between Markua 0.30 and LFM. This list highlights 10
of the more important ones...
1. In LFM, parts are created with `-# Part`. In Markua, parts are created with
a `{class: part}` attribute list above an atx (`# Foo`) or Setext (using
`===`) chapter heading.
2. In LFM, there is a special syntax for inserting code samples:
`<<[Optional Title](code/some_code_file.rb)`. In Markua, however, code
is just a resource, and the LFM syntax is not supported.
3. In LFM, to mark code as added or removed, the magic words were
`leanpub-start-insert`, `leanpub-end-insert`, `leanpub-start-delete` and
`leanpub-end-delete`. In Markua, the magic words are `markua-start-insert`,
`markua-end-insert`, `markua-start-delete` and `markua-end-delete`.
4. In LFM, there is a special syntax for inserting math: `{$$}...{/$$}`. 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.
5. In LFM, there are `G>` "generic boxes". In Markua, these are replaced with
blurbs (`B>`).
6. LFM had the `C>` syntax to center text, but we didn't have the same effect on
generic boxes, and blurbs did not exist. In Markua, a `C>` 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
`{class: center}` attribute.
7. LFM had `{rtl}` and `{ltr}` directives. These are not supported in Markua,
and neither is a `{dir}` attribute in general: any given language is either a
left-to-right or a right-to-left language, so specifying the language with
the `lang` document setting and the `{lang: ___}` directive is sufficient.
8. LFM used Sample.txt to define the sample content. Markua moves the definition
of what constitutes sample content into a `{sample: true}` 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.)
9. 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.)
10. Most importantly, a number of features (courses, index entries, smart
crosslinks, etc.) exist in Markua and do not exist in LFM.
</div>
<div class="extension">
## Migrating a Leanpub Flavoured Markdown (LFM) Book to Markua 0.30 (M)
Migrating a Leanpub Flavoured Markdown (LFM) Book to Markua 0.30 is actually
really easy.
Here are the steps you do:
1. Move the images folder inside a resources folder.
2. Convert the part syntax, if you use parts.
3. Generate the book, look at the output, and make any other changes needed.
These are all described below.
### Move the images folder inside a resources folder
In LFM, images live here:
```
manuscript/images/some_image.png
```
To convert this to Markua 0.30, the simplest thing to do is just move the images
folder inside the resources folder:
```
manuscript/resources/images/some_image.png
```
This way, your image paths will be unchanged (as they will both start
with `images/`).
### Convert the part syntax, if you use parts
In LFM, parts are defined like this:
```
-# Some Part Title
```
To convert this to Markua 0.30, you do this:
```
{class: part}
# Some Part Title
```
### Generate the book, look at the output, and make any other changes needed
The above list of changes are the main ones, but there are
[other differences](#markua-0-30-vs-leanpub-flavoured-markdown-lfm-m-) between
LFM and Markua 0.30.
However, at this point, the best thing to do is to just generate the book using
Markua 0.30 instead of LFM, and see what is produced. Then, consult that list
and the [LFM manual](https://leanpub.com/lfm/read) to learn more about how to
make any other changes needed to finish the migration.
One thing that Markua 0.30 defines which is not done in LFM is the concept of
document settings, which are a set of global switches which customize the
output of your book. You will want to review the
[standard document settings](#the-standard-document-settings-m-) section below
to learn more.
</div>
<div class="extension">
## Markua 0.30 vs. Markua 0.10 (M)
If you are writing a new book on Leanpub, you should absolutely choose
Markua 0.30 over Markua 0.10.
If you are writing a new course on Leanpub, you're stuck with Markua 0.10
for a while longer: our Markua 0.30 support don't support courses yet.
Leanpub's Markua 0.10 support is fully documented in its own [user
manual](https://leanpub.com/markua/read). Everything documented in that
manual should work as described for Markua 0.10 books and courses, and our
Markua 0.10 version will continue to be supported for years to come.
Leanpub's Markua 0.10 support is based on a private fork of an open source
Ruby library. It is not based on CommonMark or Pandoc. So, there are a
number of quirks to our Markua 0.10 support. If you are using Markua 0.10
on Leanpub, consult the [user manual](https://leanpub.com/markua/read), NOT
this spec.
</div>
<div class="extension">
## Migrating a Markua 0.10 Book to Markua 0.30 (M)
When I defined how Markua 0.10 worked, I was a number of years younger than I
am now. I cared less about compatibility with Markdown defaults, and more about
trying to fix what I thought were mistakes.
This was youthful hubris, which Markua 0.30 corrects.
What Markua 0.30 does is functions like Markdown (minus inline HTML, and
then extended) by default, but also provides the ability to override
behavior using global [document settings](#document-settings-m-). These
document settings allow you to customize the behavior of an entire Markua
document via global switches. This way, the behavior of a Markua 0.30
document can be changed in sweeping ways via these global settings.
If you are updating a large Markua 0.10 document to Markua 0.30, you will
probably want to start by doing these three steps:
1. Rename all `caption` attributes to `title`
2. Preview the book
3. Update any document settings
These are all described below.
### Rename all `caption` attributes to `title`
First, you will want to do a find-replace in your Markua manuscript to update
all `caption:` attributes to be `title:`, since the `caption` attribute was
renamed to `title` in Markua 0.30 for consistency.
Now, if you're like most Leanpub authors who wrote in Markua 0.10, chances
are you did not use any `caption` attributes, but instead relied on the
`alt-title` behavior. The `alt-title` document setting is discussed
[in great detail here](#the-alt-title-document-setting-m-).
### Preview the book
Before making any more changes, you should preview your book to see what it
looks like unchanged.
### Update any document settings
After previewing the book, you will want to review the PDF output and decide on
the appropriate values of the document settings.
If you want maximum compatibility with Markua 0.10, you will want to override
the `soft-breaks` and `two-space-hack` settings as follows:
1. Set the `soft-breaks` setting to `break`
2. Set the `two-space-hack` setting to `false`
Note that both of these settings are against the default behavior of Markdown,
so unless you are already relying on that behaviour in Markua 0.10, you should
consider leaving them at their default values.
You can change these settings on Leanpub in the Settings > Generation Settings
section of the author app, or you can set the document settings at the top of
the first manuscript file like this:
```
{
soft-breaks: break
two-space-hack: false
}
# Chapter One
Lorem ipsum dolor...
```
Make sure you add a blank line below the document settings, and also make sure
you put the curly braces on lines by themselves!
Note that you only define this list of document settings **once**, at the start
of your **first file** in your Markua manuscript.
Besides the specifics of the `soft-breaks` and the `two-space-hack`
document settings, the big point is that regardless of whether you are
upgrading a large Markua 0.10 document to Markua 0.30 or starting a new
Markua 0.30 document, you can make sweeping changes to how a Markua 0.30
document functions with a little bit of metadata at the top.
I strongly recommend that you review all of
the [document settings](#document-settings-m-) to learn what choices are
available, and decide which make sense for you. There's no one true right
answer here; it's entirely based on personal preference and whether you are
starting a new book or upgrading an existing one.
</div>
<div class="extension">
## Origin and structure of this document (M)
This is the Markua Spec, written by
[Peter Armstrong](https://twitter.com/peterarmstrong).
The Markua Spec is based on the CommonMark Spec, whose author is
[John MacFarlane](https://johnmacfarlane.net/).
This document also incorporates the specification of two of the five GitHub
Flavored Markdown (GFM) extensions from the [GFM
Spec](https://github.github.com/gfm/).
Like the CommonMark Spec and the GFM Spec, the Markua Spec is licensed under
the Creative Commons license
[CC-BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/).
This document has two types of intended readers:
1. authors with advanced questions about Markua syntax
2. developers implementing Markua Processors
The Markua Spec is a strange hybrid of the CommonMark Spec, the GFM Spec and the
specification of the Markua extensions.
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.
Next, two of the five GFM extensions are added. These are discussed
[below](#github-flavored-markdown-gfm-extension-status-m-).
Finally, many new chapters or sections about Markua are added. These are all
labeled with "(Markua extension)".
So, for any given chapter or section of this document, it is either:
1. written by John MacFarlane about CommonMark
2. written by GitHub employees about GFM, and ending with "(GFM)"
3. written by Peter Armstrong about Markua, and ending with "(M)"
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.
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.
While this hybrid approach of creating the Markua specification is somewhat odd,
it has a number of significant benefits:
1. 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.
2. 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.
3. 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.
4. 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.
5. It means that updating this document to keep it current with the CommonMark
and GFM specs will be very easy.
In terms of the GFM extensions, the following two GFM extensions are included
in the Markua Spec:
1. [Tables (GFM)](#tables-gfm-)
2. [Strikethrough (GFM)](#strikethrough-gfm-)
Their content is unchanged, but their titles are renamed to say "(GFM
extension)" instead of "(extension)", to more clearly specify their provenance.
The other three GFM extensions are omitted:
1. [Task list items](https://github.github.com/gfm/#task-list-items-extension-)
is omitted since Markua is for books and courses, not task lists.
2. [Disallowed Raw HTML](https://github.github.com/gfm/#disallowed-raw-html-extension-)
is omitted since Markua goes farther and **completely removes all raw HTML**,
both HTML added as HTML blocks or as raw HTML inlines.
3. [Autolinks](https://github.github.com/gfm/#autolinks-extension-) is omitted,
because the extra work to create a link is literally typing two characters
(`<` and `>`), 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.)
</div>
<div class="extension">
## About the HTML output (M)
The HTML mapping defined in this specification is NOT a complete specification
of the HTML documents produced by Markua Processors.
Also, the HTML mapping defined in the specification is NOT considered to be
canonical.
For example, consider the following Markua:
```
![a red apple](mac.jpg "The Original Mac")
```
A Markua Processor can produce HTML that looks like this:
```
<p><img src="mac.jpg" alt="a red apple" title="The Original Mac" /></p>
```
(That is what was produced at <https://spec.commonmark.org/dingus/> on
2020-05-27, for example, and it is valid Markua as well as valid CommonMark.)
A Markua Processor can also, however, produce HTML that looks like this:
```
<p>
<figure>
<img src="mac.jpg"
alt="a red apple">
<figcaption>The Original Mac</figcaption>
</figure>
</p>
```
Both approaches are completely legitimate, and have pros and cons.
So, why show any HTML at all? There are two reasons:
1. The CommonMark Spec shows HTML, and the Markua Spec tries to only be additive
to the CommonMark Spec.
2. Showing HTML helps Markua Processors to test their parsers.
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.
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.
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.
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.
</div>
<div class="extension">
## Why the name "Markua"? (M)
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.
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.
</div>
## What is Markdown?
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
[syntax description](https://daringfireball.net/projects/markdown/syntax)
and a Perl script (`Markdown.pl`) 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.
What distinguishes Markdown from many other lightweight markup
syntaxes, which are often easier to write, is its readability.
As Gruber writes:
> 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.
> (<https://daringfireball.net/projects/markdown/>)
The point can be illustrated by comparing a sample of
[AsciiDoc](https://asciidoc.org/) with
an equivalent sample of Markdown. Here is a sample of
AsciiDoc from the AsciiDoc manual:
```
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.
--
```
And here is the equivalent in Markdown:
```
1. List item one.
List item one continued with a second paragraph followed by an
Indented block.