Appendices

No Inline HTML

Inline HTML, in which HTML is inserted directly in the content of a Markua document, is not supported in Markua.

HTML is just one possible output format, and other possible Markua output formats (such as PDF) are not based on HTML. If inline HTML was supported, Leanpub would have to support parsing and meaningfully outputting all of HTML syntax as well as all of Markua syntax.

Markua and Markdown have different use cases. Markdown is a better way to write HTML; Markua is a better way to write a book. Since Markdown’s only output format target is HTML, it might as well support inline HTML: generating HTML from HTML is as simple as passing the HTML through. From an implementation perspective, Markdown gets inline HTML support for free.

Note that by “Markdown” in the previous paragraph, I mean the format originally defined by John Gruber, best-specified by CommonMark and extended by formats such as GitHub Flavored Markdown. All of these forms of Markdown DO support inline HTML. However, Leanpub Flavoured Markdown does NOT support inline HTML, even though it has “Markdown” as part of its name. Leanpub Flavoured Markdown (the predecessor of Markua on Leanpub) is basically Markdown plus some extensions minus inline HTML. So, Leanpub does not support inline HTML, regardless of whether you use Markua or Leanpub Flavoured Markdown.

By not supporting inline HTML, Markua imposes more constraints on writers who would be tempted to use inline HTML for layout purposes. Since Markua does not support inline HTML, attempting to do complex layout in Markua using HTML is just not possible. And since it’s not possible, the temptation to procrastinate by doing formatting is reduced.

Now, one design benefit of the support for inline HTML in Markdown is that Markdown’s syntax can stay artificially small–since Markdown authors can always fall back to using HTML directly, Markdown does not need to be able to produce all of HTML. Since Markua does not support inline HTML, Markua must contain all concepts that it supports directly expressed using Markua syntax. For example, there is no official table syntax in Markdown, and Markdown authors can just use inline HTML tables. Since Markua does not support inline HTML, and since books often require tables, Markua needs to add a table syntax.

Differences with Markdown

Markua has a number of differences from Markdown as defined by John Gruber.

These are the main ones:

  1. In Markdown, *one asterisk* and _one underscore_ both produce italics. In Markua, *one asterisk* produces italics, and _one underscore_ produces an underline unless the italicize-underlines global setting is set to true.
  2. Markdown supports inline HTML; as discussed earlier, Markua does not.
  3. Markua defines many more types of numbered list numbering than Markdown. In Markdown, the only type of numbering supported is decimal numbering starting from 1. If you need any more features, you need to use inline HTML. However, since Markua does not support inline HTML, Markua provides more list types and features.
  4. Unlike in Markdown, in Markua the number that begins the list in the manuscript is the number that begins the list in the output.
  5. Markdown does not specify a table syntax. Since Markdown supports inline HTML, it does not need to–if you want a table, you can simply use an inline HTML table. Since Markua does not support inline HTML, Markua uses the GFM table syntax.
  6. Markua supports definition lists; Markdown does not (except via inline HTML).
  7. Markdown lets you use a plus sign (+) before each item in an unordered (“bulleted” in Markua) list; Markua does not. Having three syntaxes is just overkill, so Markua drops the plus–it’s far less common than the asterisk and hyphen. This is the same decision made by GitHub Flavored Markdown, which also supports * and - but not +.
  8. Markdown does not support closing parentheses ()) as ordered (“numbered” in Markua) list delimiters; Markua does.
  9. Markua and Markdown currently handle spaces, newlines and indentation differently. This is discussed in the Whitespace: Spaces, Tabs and Newlines section.
  10. Markdown’s reference link syntax and its implicit link name shortcuts are currently not supported in Markua.
  11. Markua’s heading syntax is currently a subset of Markua’s atx headers.
  12. The backtick syntax of adding inline code resources as spans is identical to the code span syntax of Markdown, however the optional attribute list is Markua-specific.
  13. The syntax for inline code resource figures is similar to the “fenced code blocks” syntax of many Markdown extensions, such as PHP Markdown Extra and GitHub Flavoured Markdown.
  14. The “four space indent” method of creating code blocks in Markdown is currently not supported in Markua.
  15. In Markdown links, a URL can be either absolute (starting with http:// or https://) or relative (just referring to a path like /foo/bar.html), since relative URLs can make sense when writing blog posts which live on web servers. In Markua, however, all URLs must be absolute.