This question was a sensation in 2015.

You’re probably wondering: what’s the point of those things like :buttons and #dress?

The :buttons tag says, “this is not an ordinary Markdown list, it’s a TigYog button list”. To get an ordinary bulleted list, just ensure the previous paragraph does not include a :buttons marker.

In the above example, #dress, #black and #white are identifiers. They solve the following problem. Imagine a reader clicks “Black and blue”. Then later you edit the button text to “Black & Blue”. When the reader comes back, it should show that they chose “Black & Blue”. To allow this, TigYog needs to know that it’s still “the same button”, even though the text has changed.

To solve this, we give an id to each button list and to each button. Above, the prompt has id dress, and its two buttons have ids black and white. A button’s id is that of the first paragraph in the list item. A prompt's id is that of the paragraph before it.

Or, more precisely:

A Markdown list is a button list with id X if the paragraph before the Markdown list contains :buttons{#X}. (This is a Markdown text directive.)

A Markdown list item is a button with id Y if its first paragraph contains :button{#Y}.

To write a real conversation, you’ll want to respond to specific buttons:

The first paragraph in a list item is the button text. Any subsequent paragraphs are a response to that button. Notice that you can embed further prompts in a response. You can build complex conversation trees this way!

Here’s that conversation tree — explore it using the “Redo” button:

But before we get to work, are you hungry?

(End of conversation tree here!)

You can use a single-item list for “Continue” buttons:

This appears like so:

Above, the prompt and the button both have id 2Gs. More precisely: if a button list does not have an id preceding it, it will use the id of its first button.

This lets you build freeform conversation. But TigYog also has a notion of correct and incorrect answers.

This renders like this:

Which are better, cats or dogs?

If the attribute block contains .correct, then the button is marked as correct, and that paragraph is ignored. If it contains .incorrect, the button is marked incorrect. If it contains neither, it’s ... just a button.

I’ve designed the TigYog-Flavored Markdown format with the following principles.

Lightweight. Should feel like Markdown: short and easy to type.

Familiar. No new syntax, to the greatest extent possible. The :foo{#id .class} syntax is a CommonMark “generic directive.”

Existing Markdown content should render as expected. TigYog-Flavored Markdown is a superset of Markdown.

Should be readable in existing Markdown renderers. For example, GitHub’s markdown preview is not aware of buttons or responses. However, you may still want to read your TigYog content in that previewer.

Should be editable in existing Markdown editors. For example, Obsidian is not aware of buttons or responses. However, you may still want to use it to edit your TigYog content.

If you have suggestions for improvement (without syntax bikeshedding), let me know!

Not all block types are supported yet. We will soon support:

Images

Chapter links

Buy buttons

Paywalls

Alternatively, you can write your content in .tigyog.md files, and deploy using git or the TigYog API.

A file ending in .tigyog.md is TigYog-Flavored Markdown (or TFM).

Ids are important, but you don’t want to think, type, or read them.

You should auto-generates id with tigyog fmt.

Say you have this file:

Run tigyog fmt and you'll get:

tigyog fmt looks at each Markdown list. If you signal with :buttons that it should be a button list, tigyog fmt generates ids for it as [A-Za-z0-9]{3}.

Despite the earlier example, we recommend you avoid handwritten ids like sqrt64 or eight. Ids should be arbitrary; their only important property is uniqueness.

You can integrate tigyog fmt into your IDE. In Visual Studio Code, use Shift+Alt+F (“Format Document”).