Introduction to QText

QText is Querki's "wikitext" language -- basically a simplified markup language to do the commonly-used parts of HTML.

It is based directly on Markdown, and most Markdown syntax will work exactly as expected. That said, we aren't calling it Markdown because we are explicitly planning on evolving it pretty quickly, and it may eventually wind up incompatible.

Currently, HTML is not permitted in Text; if you try, you probably won't get the results you expect. This restriction is across-the-board, but will be relaxed in the near future, to permit whitelisting of some HTML constructs. However, there are some parts of HTML that will probably never be permitted (eg, script tags), and you shouldn't count on anything. If you have need of a specific HTML tag, make a request -- as with everything, user demand will affect when that feature gets added.

That said, the broad strokes of Markdown are still correct, and probably will remain so; see the Markdown documentation for details on the basics. There are already a few additions to Markdown that are worth knowing about, and more being planned:

Linking to the received Context: as mentioned in the Introduction to QL, you can surround some text with double-underscores __like this__ to turn it into a link to the received Context; that is the usual way to control the text displayed for a link. If you want the link, but are okay with just using the Display Name, you can simply say ____ -- four underscores -- and it will simply result in the default link to the received Context.

(Note that, technically, the four-underscore version works for any received Context, and will render it in the Type's default way. If the context is an Integer, it will include that; if it is Text, it'll show that; and so on. But nine times out of ten, you will use this construct for links.)

Styles: Querki stylesheets will be discussed in much more detail later in this booklet, but suffice it to say, Querki has pretty complete CSS support. In general, you should use HTML classes to style things. To support this, there is a special new construct in QText, which comes in two varieties: {{classname: ...}} This inserts an HTML span tag, with the specified CSS class, around the surrounded text. {{classname: ... }} This inserts an HTML div tag, with the specified CSS class, around the surrounded text.

That is, if it's all on one line, it becomes a span; if the construct is on separate lines from the text, it becomes a div. These two constructs aren't quite enough to do everything in CSS. (Which is why we will eventually begin whitelisting some HTML tags.) But they are enough to easily add a lot of basic styles.

Deeper list nesting: one of the Markdown limitations that drives me personally insane is that you can only do one level of bullet list in conventional Markdown. We will likely enhance things so that multiple asterisks at the beginning of a line indicates more deeply-nested lists.

Table support: Markdown doesn't deal with tables at all. We will be whitelisting the basic table tags, but I also plan to add wikitext support for simple table layout. Opinions about preferred syntax are welcomed.

Support for some Gadgets: as we learn what client-side gadgets are useful, we will likely provide QText support for the more commonly-used one. For example, I suspect that we will add a simple syntax for declaring accordion lists.