QText Reference

QText is a "wikitext"-style format, and is what goes in any Text or Large Text Property. It is loosely based on Markdown (in fact, we started with a Markdown parser, and have been evolving from there), and for more details on some of this you may want to look at the Markdown page. But it is gradually diverging from Markdown, since Querki's priorities are different..

The focus of QText is to be an easy way to create nicely-formatted text, that is as intuitive as possible. In many cases, you can just type what makes sense, and it simply works. But this page is a quick reference to the details, so you can know what does and doesn't work. The order here is mainly how common things are. The absolutely everyday stuff is at the top, the less-important at the bottom. For a brief table showing the most commonly-used markup, see Introduction to QText.

Text Styles

Emphasis: Italics and Bold

To italicize a word or phrase, just surround it with asterisks:

This is *fairly* important.

becomes:

This is fairly important.

To boldface them, surround with double-asterisks instead:

This is **very** important.

becomes:

This is very important.

Markdown allows you to use underscores to do this instead of asterisks. That is still possible in QText, but not recommended: we may reclaim underscores to mean something else instead, like underlining.

Strikethrough

(QText enhancement from Markdown.)

To strike through a word or phrase, surround it with double-dashes:

I --do-- don't want that.

becomes:

I do don't want that.

Paragraphs

You start a new paragraph simply by double-spacing:

This is paragraph 1.

This is paragraph 2.

Becomes:

This is paragraph 1.

This is paragraph 2.

Line Breaks

If you want two lines to be right next to each other, you have to end the first line with two spaces. It isn't obvious, but the first line here has two spaces at the end:

This is line 1.  
This is line 2.

Which becomes:

This is line 1.
This is line 2.

Run-on Paragraphs

Note that QText currently smooshes successive lines together into a single paragraph:

This is my first line.
This is my second line.

Becomes:

This is my first line. This is my second line.

It isn't entirely clear that this is ideal for Querki. It isn't as necessary as it is with some editors, since you can just type long paragraphs in Querki without putting in newlines, and most browsers will word-wrap nicely. And the thing about having to put two spaces at the end of the line to get a line break is, in my opinion, one of Markdown's weaknesses -- it's hard to remember, and tends to lead to surprises.

So opinions would be welcomed -- should we change things so that a line break in the original text becomes one in the results? I'm seriously considering this, and would love user input. (No guarantees, though: Markdown is a subtle languages, and we'd need to think carefully about their rationale for the way they do things.)

Headers

The main way to create a Header is to begin the line with a certain number of hashes ("#" signs). You can have 1 to 6 hashes, which says which "level" of Header to use -- level 1 is very large, whereas level 6 is quite small:

### This is a level 3 Header

Becomes:

This is a level 3 Header

Note that Markdown has two distinct ways to show Headers. This one is "atx" style. The other is "Setext" style, and looks like this:

This is level 2
-----------------

which becomes:

This is level 2

I personally dislike this approach. It only works for Levels 1 and 2 (which are bigger than you usually want in a Querki page), and it winds up causing tons of confusion with horizontal rules (described below). So it is likely to be removed from QText in the future; please do not use it.

Blockquotes

You show a blockquote -- a quoted section that is inset a bit -- by starting the line with "> ":

> This is my quote.  It doesn't have to be a quote per se, but it's the easy way to create an inset like this.

Becomes:

This is my quote. It doesn't have to be a quote per se, but it's the easy way to create an inset like this.

Markdown recommends using a lot of hard line-breaks for a long quote, like this:

> This is a long quote, which runs on for a while and blathers and will probably get into
> lorem ipsum text after a while, simply because I need enough to put in here to illustrate
> the point.  Oh, look, here it comes:
>
> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin et semper ante, blandit dapibus metus. Fusce eu
> ante nunc. In cursus ultrices massa. Nulla et orci in justo porttitor blandit. Donec sit amet elit fermentum, laoreet
> nunc eleifend, egestas metus. Curabitur imperdiet est dolor. Praesent pretium, sapien non sollicitudin fringilla,
> turpis felis ultrices elit, at imperdiet elit risus eu risus. Cras quis metus nec elit egestas imperdiet ut id dolor. Fusce
> varius pulvinar auctor. Integer vitae turpis felis. Nunc nibh lacus, sollicitudin imperdiet tempor sit amet, feugiat in
> ante. Nam fringilla tincidunt nulla, in lacinia quam auctor quis. Aliquam erat volutpat.

Which becomes:

This is a long quote, which runs on for a while and blathers and will probably get into lorem ipsum text after a while, simply because I need enough to put in here to illustrate the point. Oh, look, here it comes:
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin et semper ante, blandit dapibus metus. Fusce eu ante nunc. In cursus ultrices massa. Nulla et orci in justo porttitor blandit. Donec sit amet elit fermentum, laoreet nunc eleifend, egestas metus. Curabitur imperdiet est dolor. Praesent pretium, sapien non sollicitudin fringilla, turpis felis ultrices elit, at imperdiet elit risus eu risus. Cras quis metus nec elit egestas imperdiet ut id dolor. Fusce varius pulvinar auctor. Integer vitae turpis felis. Nunc nibh lacus, sollicitudin imperdiet tempor sit amet, feugiat in ante. Nam fringilla tincidunt nulla, in lacinia quam auctor quis. Aliquam erat volutpat.

Their argument is that this looks better in your original text, which is somewhat true but doesn't match the reality of modern variable-width screens and ubiquitous word wrapping. (Look at the above on a phone, and it doesn't look nearly as good.) So I recommend not worrying about this, just using one long line per paragraph, and letting the browser word-wrap for you.

Lists

There are several different kinds of lists in HTML. In QText, they work like this.

Bullet Lists

To make a bullet list, just start each line with an asterisk:

* Red
* Green
* Blue

Becomes:

Red
Green
Blue

Markdown allows you to begin your lines with "+" and "-" as well to produce bullet lists. This is not recommended in Querki: I suspect that we will reclaim those characters to mean something else later. So use "*" in QText.

Note that "List" is one of the main types in Querki, and you will often have Lists or Sets in your data. Displaying those involves using QL (the language for handling data in Querki) together with QText, but there is a special command, "_bulleted", for showing bullet lists, since it is so common.

So say I have a List of Text, named "My List", whose elements are "Red", "Green" and "Blue". I can display that as a bullet list by saying:

[[My List -> _bulleted]]

Numbered Lists

You create a numbered list by starting each line with a number and a period, like this:

1. Red
1. Green
1. Blue

Which becomes:

Red
Green
Blue

Note that the numbers you use in the original don't matter -- QText will renumber them when it shows them. If you want your source text and the display to look alike, you could number them "1.", "2.", "3.". That is okay, but it tends to break down when you change your text and do something like delete a line. So I recommend just using "1." for each line, to remind yourself that these numbers aren't necessarily permanent.

Definition Lists

(QText enhancement from Markdown.)

To show a definition list -- a set of terms and definitions -- you use a pair of colons like this:

: do : a deer, a female deer
: re : a drop of golden sun
: mi : a name, I call myself
: fa : a long, long way to run

Which shows like this:

do: a deer, a female deer
re: a drop of golden sun
mi: a name, I call myself
fa: a long, long way to run

Multi-paragraph List Items

(Not currently working.)

Sometimes, you want an element in a bullet list to be especially long. You can have multiple lines in a given item by indenting each successive line with four spaces, like this:

* Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin et semper ante, blandit dapibus metus. Fusce eu ante nunc. In cursus ultrices massa. Nulla et orci in justo porttitor blandit. Donec sit amet elit fermentum, laoreet nunc eleifend, egestas metus. Curabitur imperdiet est dolor. Praesent pretium, sapien non sollicitudin fringilla, turpis felis ultrices elit, at imperdiet elit risus eu risus. Cras quis metus nec elit egestas imperdiet ut id dolor. Fusce varius pulvinar auctor. Integer vitae turpis felis. Nunc nibh lacus, sollicitudin imperdiet tempor sit amet, feugiat in ante. Nam fringilla tincidunt nulla, in lacinia quam auctor quis. Aliquam erat volutpat.

    Sed vestibulum hendrerit sodales. Praesent gravida ornare facilisis. Ut imperdiet dapibus quam. Phasellus in neque lacus. Quisque pretium ipsum vel risus rhoncus pretium. Interdum et malesuada fames ac ante ipsum primis in faucibus. Quisque nec dui non tellus dignissim condimentum at id lacus.

* Suspendisse ac lorem eu nulla rhoncus molestie. Aenean suscipit libero ut leo ultricies, at luctus justo blandit. Vivamus ac tempor erat. Quisque euismod augue enim. Etiam pretium fermentum est, ut convallis lorem gravida a. Fusce sed leo et sapien accumsan malesuada nec vel sapien. Sed bibendum diam at malesuada volutpat. Aliquam feugiat tincidunt dolor nec molestie.

    Duis vulputate, ligula at congue molestie, purus erat sagittis erat, eleifend volutpat arcu nisl at velit. In mattis dolor et venenatis laoreet. Duis facilisis quam et feugiat facilisis. Aliquam viverra lacus vitae gravida mollis. Pellentesque tincidunt fringilla dolor, sit amet eleifend dolor faucibus sit amet. Suspendisse ac sem at ipsum bibendum porta. Donec ac lacus laoreet, tincidunt tellus vel, hendrerit lacus. In tincidunt urna non tempor ullamcorper. Nunc et lacus mi. Aenean felis nulla, dapibus sit amet commodo in, tristique nec nulla. Nam at ipsum sapien.

    Morbi nibh arcu, elementum at diam non, placerat fringilla est. Ut eget vehicula leo. Curabitur mattis ac nisl eu porttitor. Quisque eu fringilla velit. Sed ut dui sit amet diam feugiat vulputate. Quisque sapien ante, bibendum quis nibh iaculis, malesuada eleifend leo. Nunc venenatis orci nisi, non aliquet sem aliquam nec. In blandit nisi vel tellus lacinia, non sollicitudin eros lacinia. Nulla eu ante vestibulum augue suscipit rhoncus. Sed sit amet nibh et est tincidunt tristique non vitae nulla. Nunc iaculis tortor vitae quam facilisis suscipit. In blandit libero a mi convallis aliquet ut id diam. Morbi et elit luctus, lobortis nisi ac, dapibus nisl. Cras lacinia ac nibh eu tincidunt.

which displays as:

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin et semper ante, blandit dapibus metus. Fusce eu ante nunc. In cursus ultrices massa. Nulla et orci in justo porttitor blandit. Donec sit amet elit fermentum, laoreet nunc eleifend, egestas metus. Curabitur imperdiet est dolor. Praesent pretium, sapien non sollicitudin fringilla, turpis felis ultrices elit, at imperdiet elit risus eu risus. Cras quis metus nec elit egestas imperdiet ut id dolor. Fusce varius pulvinar auctor. Integer vitae turpis felis. Nunc nibh lacus, sollicitudin imperdiet tempor sit amet, feugiat in ante. Nam fringilla tincidunt nulla, in lacinia quam auctor quis. Aliquam erat volutpat.

Sed vestibulum hendrerit sodales. Praesent gravida ornare facilisis. Ut imperdiet dapibus quam. Phasellus in neque lacus. Quisque pretium ipsum vel risus rhoncus pretium. Interdum et malesuada fames ac ante ipsum primis in faucibus. Quisque nec dui non tellus dignissim condimentum at id lacus.

Suspendisse ac lorem eu nulla rhoncus molestie. Aenean suscipit libero ut leo ultricies, at luctus justo blandit. Vivamus ac tempor erat. Quisque euismod augue enim. Etiam pretium fermentum est, ut convallis lorem gravida a. Fusce sed leo et sapien accumsan malesuada nec vel sapien. Sed bibendum diam at malesuada volutpat. Aliquam feugiat tincidunt dolor nec molestie.

Duis vulputate, ligula at congue molestie, purus erat sagittis erat, eleifend volutpat arcu nisl at velit. In mattis dolor et venenatis laoreet. Duis facilisis quam et feugiat facilisis. Aliquam viverra lacus vitae gravida mollis. Pellentesque tincidunt fringilla dolor, sit amet eleifend dolor faucibus sit amet. Suspendisse ac sem at ipsum bibendum porta. Donec ac lacus laoreet, tincidunt tellus vel, hendrerit lacus. In tincidunt urna non tempor ullamcorper. Nunc et lacus mi. Aenean felis nulla, dapibus sit amet commodo in, tristique nec nulla. Nam at ipsum sapien.

Morbi nibh arcu, elementum at diam non, placerat fringilla est. Ut eget vehicula leo. Curabitur mattis ac nisl eu porttitor. Quisque eu fringilla velit. Sed ut dui sit amet diam feugiat vulputate. Quisque sapien ante, bibendum quis nibh iaculis, malesuada eleifend leo. Nunc venenatis orci nisi, non aliquet sem aliquam nec. In blandit nisi vel tellus lacinia, non sollicitudin eros lacinia. Nulla eu ante vestibulum augue suscipit rhoncus. Sed sit amet nibh et est tincidunt tristique non vitae nulla. Nunc iaculis tortor vitae quam facilisis suscipit. In blandit libero a mi convallis aliquet ut id diam. Morbi et elit luctus, lobortis nisi ac, dapibus nisl. Cras lacinia ac nibh eu tincidunt.

Links

Links are the heart and soul of the Web -- they're how you go page-to-page. Querki has rather different mechanisms, depending on whether you are linking to something else within this Space, or a page outside of it.

Local Links

Most of the time, you care about Local Links -- links to other Things in this Space. Those are actually done in QL rather than QText, but they're easy. If you want to point to a Thing named "My Other Thing", you just say:

[[My Other Thing]]

Note the double-square-brackets around the name -- that is what says that this is a QL Expression, and the simplest QL Expression is simply linking to another Thing. That will show up as:

My Other Thing

Keep in mind that what you put in the double-square-brackets is the Link Name of the Thing, but what shows up is the Name. Most of the time these will be the same, but Link Names can only contain letters, digits and spaces. If you want to link to the actual Name, and it contains special character, you must put it into back-ticks, like this:

[[`Thing With Exclamation point!`]]

. You can also link directly to something by its OID:

[[.3y29a86]]

External Links

To link to something elsewhere on the Web (including Things in other Spaces in Querki), you have to use the full URL, like this:

[Link to the Querki Homepage](http://www.querki.net/)

which shows up as an ordinary link:

Link to the Querki Homepage

Markdown has an additional syntax, called "reference links", which allows you to collect all of your URLs at the bottom of the page instead, sort of like footnotes. That isn't very Querki-ish, and will likely go away.

Markdown also allows you to define an external link simply by surrounding a URL with angle brackets. This has been removed, because it interferes with using HTML on your pages.

Images

To embed an image, the syntax is a lot like that of an external link, but with an exclamation point at the front:

![Querki Logo](http://www.querki.net/assets/images/Logo-green.png)

is the way to display:

The text in the square brackets is the "alt text", that will be used for assistive devices and the like.

You can also define Properties of Type Photo, and upload images into those; you display those simply by naming the Property, as you do for any other Property.

Style: Spans and Divs

(QText enhancement)

A key concept in modern HTML is the Stylesheet, which allows you to describe a "style" -- the sizes, colors, and layout of your text -- and then apply it to parts of your page. Querki takes styles very seriously: while they are totally unnecessary for a utilitarian Space (and you should feel free to ignore them if you don't need them), they are essential for creating a really pretty one.

The full details of creating a Stylesheet are outside the scope of this document. But if you already know CSS, the process is basically:

Create an instance of the Stylesheet Model.
Fill in the CSS property. (The allowed CSS is a slightly restricted subset, but most of what you want will be okay.)
On the page where you want to use the Stylesheet, add the Stylesheet Link Property, and point it to that Stylesheet. (Or, to use the Stylesheet throughout your Space, just add the Stylesheet Link to the Space itself.)

Then the question is, how do you use those styles? QText makes it easy, with the {{ construct. For example, using the built-in _smallSubtitle style:

{{_smallSubtitle:
(Here is my small subtitle)
}}

which shows as:

(Here is my small subtitle)

You can combine multiple styles in a single declaration. For example, say that I have styles named emColor, which shows emphasis in red, and emBold, which shows it as boldfaced. I can use the two together like this:

{{emColor emBold:
This is very important!
}}

which shows as:

This is very important!

That is how you create an entire paragraph or section (technically, a "div") with the style: you have the beginning and end of the {{ tags on their own lines. To use a style inline (technically, a "span"), it's just the same thing, but you put it all on the same line. Say that I have the following style (which is defined in this documentation's Stylesheet):

.superEmphasized {
  font-weight: bold;
  font-style: italic;
  color: red;
}

I can use that in a line like this:

Here is something {{superEmphasized:very important}}, that you must pay attention to!

The result shows as:

Here is something very important, that you must pay attention to!

You can can list multiple styles within the tag (separated by spaces).

Querki is built upon Twitter Bootstrap, a big library with tons of useful styles and tools, many of which you can invoke directly using this simple tag. Feel free to use the elements of Bootstrap, but please note that Querki is currently using Bootstrap 3.0. When Bootstrap 4 comes out, we'll examine how best to migrate to that.

Code Blocks

You'll note the code blocks embedded in this page -- the insets in monospace font, where no QText gets interpreted. Those are created by surrounding the block with "```" -- lines consisting of just three backticks. This is a good, easy way to embed programming code in a page.

You can also embed a code block inline, like this, by surrounding it with single backticks.

Markdown allows you to define a code block simply by indenting by four spaces. That proves to work poorly in the Querki environment, so that feature has been removed from QText -- use the three-backticks style instead.

QL Blocks

Expressions of QL -- Querki's programming language -- are surrounded by double-square-brackets, like this:

[[My List -> _bulleted]]

But if you just surround that with "```", it will evaluate that expression, rather than printing it literally. So how do you display QL? You surround it with "[[```" and "```]]" instead. This is basically a special QL expression that means, "render this stuff literally".

Horizontal Rules

To create a line across the page, just show a line of three or more dashes by itself. (I usually use six.) So this:


------

becomes:

For the time being, you need to be very careful that there are blank lines before and after these dashes -- otherwise, they can wind up getting interpreted as headers. (This is likely to change in the future.)

Markdown allows you to use asterisks or underscores to define horizontal rules, instead of dashes. It is somewhat likely that we will use those for something else down the line, so this isn't recommended -- use a line of dashes to represent a horizontal rule.

Backslash Escapes

Occasionally, you want to show a character in a place where QText wants to do something special with it. You can prevent that by putting a backslash in front of it. For example, to literally show an asterisk at the beginning of a line, without it becoming a bullet list, you would say:

\* Some Text

which shows as:

* Some Text

Or if you want to use {{ in the middle of a line without it looking like a Style tag (as this line shows), you say:

Or if you want to use \{{ in the middle of a line without it looking like a Style tag (as this line shows), you say:

You should also generally use a backslash in front of [[, ]] and "", if you need to show those literally on the page.

By and large, if QText is being over-enthusiastic at you, a backslash is the way to make it stop doing so.

HTML

As of this writing, you can use the majority of HTML inside of QText. Not everything (for security reasons, we have to limit the HTML), but the most common tags and attributes all work.

Note that JavaScript is absolutely forbidden inside of QText. That isn't going to change: it's extremely difficult to allow JavaScript without making the system insecure, so we have no plans to add it.

Controlling Line Rendering

(This is advanced, and still slightly experimental, but seems like it is going to stay.)

As described above, QText automatically handles newlines (that is, when you say Enter at the end of a line). A single newline is simply ignored, so that lines run together; two newlines (a blank line) cause it to start a new paragraph.

Usually, this is what you want. But sometimes, when you are trying to do fancy things with layout, this gets in the way. For this reason, Querki has two additional tools, to let you control the result of your newlines.

rawLines

Sometimes, you want the newlines in your text to come out as newlines on your page; this is most often useful when your text is poetry or song. The way to do that is by bracketing them with !+rawLines and !-rawLines. For example, if you say:

 !+rawLines
 We the People,
 In order to form a more perfect union,
 Establish Justice; ensure domestic tranquility
 !-rawLines

that will come out as:

We the People,
In order to form a more perfect union,
Establish Justice; ensure domestic tranquility

(Apologies to readers of a certain age, who are now earwormed.)

Basically, instead of interpreting two newlines as a paragraph, this will simply preserve all newlines in the final result, so that everything lines up as you want.

noLines

On the other hand, sometimes newlines are just in the way. This most often happens when you are trying to do fancy things with div's, and you want Querki to specifically ignore all the newlines. You express that like this:

 !+noLines
 <div class="emBold">I am trying to do something here,

 and I want you to stop trying to introduce paragraphs into it!</div>
 !-noLines

which displays as:

I am trying to do something here, and I want you to stop trying to introduce paragraphs into it!

This example is rather contrived, but it's not unusual to hit situations like this, especially when you are doing complex layouts.

Both rawLines and noLines are technically stacks -- for instance, you can have multiple !+noLines inside each other, and things won't return to "normal" until all the matching !-noLines are reached. This is rarely relevant, but can matter when you are doing fancy things with nested Text fields.

Missing Concepts and Things to Change

QText is still a work in progress, and not everything we will need is here yet. A lot of enhancements are planned, including:

Tables -- since Querki is all about data, we're obviously going to need good, easy ways to show tables. This is not designed yet, and is likely to be one hell of a project. Syntax suggestions are welcomed, and I wouldn't mind some coding help when the time comes: tables are complicated, and getting them right isn't going to be simple.
Accordions, Tabs and other Dynamic Sections -- I've found that complex pages like this really want a nicer way to show sections. There is a lot of support for this sort of thing in the Bootstrap library that Querki uses for display -- we just don't have a good way to use that from QText yet. Syntax suggestions would be welcome for good ways to represent tabs and accordions in Querki -- I suspect that, once we get the syntax working, actually making the features work will be very easy.

What else? What do you find you desperately want, that QText doesn't have yet? We're not going to be too casual about it, but I'm entirely prepared to keep enhancing this to make it work well for Querki's users...