Learn Ducktype

Begin making a Ducktype document by writing the front page in any text editor. Generally, the front page of any document will be a guide page, as its purpose is to help users navigate to other content. In Ducktype, the front page of any document is always named index.duck.

= Beanstalk Help
  [type=guide]

This simple example is a valid Ducktype guide page. Taken alone, it is also a valid Ducktype document.

Every page starts with a title, denoted with a leading equals sign and space. Following the title, you can add a list of attributes on an indented line surrounded by square brackets. Here we have set the type attribute to guide, indicating the page is a guide page.

The type attribute is very common in Mallard and Ducktype, so Ducktype provides a shorthand syntax for it. Just omit the type= part. (There are a few other attribute shorthands, some of which will be covered in this tutorial.)

= Beanstalk Help
  [guide]

You now have a simple document, but you can only view the raw markup in a text editor. To view formatted output, you first need to convert your document to XML, then process it with a Mallard processing tool. Some tools can do this in a single step, but we'll do it in two steps.

To convert Ducktype to Mallard, use the ducktype tool, part of the mallard-ducktype package. mallard-ducktype is available on the Pythin Package Index (PyPI). Use the pip3 command to install it.

pip3 install mallard-ducktype

To convert a Ducktype page to a Mallard page, call ducktype and pass the Ducktype page as an argument.

ducktype index.duck

This will output a Mallard XML file called index.page.

The Gnome help viewer Yelp has native support for Mallard XML. You can view the document by calling yelp from the command line and passing it the full path to the directory containing the generated page file. For example, if you have placed index.page in /home/drake/mydocument/, enter this at the command line:

yelp /home/drake/mydocument/

Alternatively, you can build static HTML pages using the yelp-build tool, part of the yelp-tools package:

yelp-build html *.page

The yelp-tools package contains various utilities to help you build and manage your documentation. See http://yelp.io/tools/ for more information.

Unless you're creating a simple set of instructions for a friend or colleague, you probably want to have multiple pages in your document. Add another page to the document by creating a new file:

= Planting Beans
  [topic]

Notice that the type attribute is "guide" in index.duck and "topic" in planting.duck. Since index.duck is a guide page, it can have links inserted automatically to other pages. In Mallard and Ducktype, guides don't have to specify which pages they link to. Instead, pages can specify that guides should link to them. Do this by adding a link element to planting.duck:

= Planting Beans
  [topic]
@link[guide xref=index]

The link element here is a type of informational element. Informational elements can follow headings and block elements. They start with an at sign and have a name, then possibly an attribute list and content. In this case, the link element has two attributes: type and xref. The xref element is also very common, so Ducktype has a shorthand notation for it.

= Planting Beans
  [topic]
@link[guide >index]

The link element specifies that this page should be linked to from the guide page index, which we created above.

Convert both pages to Ducktype, then to HTML:

ducktype *.duck
yelp-build *.page

You'll see that the front page now has a link to this new page. This is one of the unique features of Mallard and Ducktype. Rather than requiring pages to specify everything they link to, Mallard allows pages to insert themselves into other guide pages. This makes it possible to add pages for plugins and additional functionality without modifying the original source pages.

You can add additional guide pages to your document. This allows you to organize content to match what your readers are looking for. Add a guide page to link to ways you can use magic beans.

= Bean Uses
  [guide]
@link[guide >index]
@link[topic >planting]

Like planting.duck, this page has a guide link to index. If you convert all the pages to HTML again, you'll see that the front page now has two links.

This page adds a new type of link. Topic links are the inverse of guide links. When a guide page has a topic link to another page, it's as if the other page had a guide link to the guide page. Despite the name, topic links can link to topic pages or guide pages.

If you view the “Planting Beans” page, you'll see it has links at the top and bottom to both “Beanstalk Help” and “Bean Uses”. Adding a page to a guide is like adding it to a section in a traditional linear document, except that pages can be linked to from multiple guides. This allows you to provide multiple ways to navigate to a page to better match how your readers are thinking.

Currently, there's no real content in planting.duck. Add content to explain to the user how to plant magic beans. The following example shows a basic paragraph and a list.

= Planting Beans
  [topic]
@link[guide >index]

By the end of this page, you will be able to plant your magic
beans and nurture them into a bean sprout.

* Dig a hole 5cm deep.
* Place your magic beans in the hole.
* Fill the hole with clean dirt and pat it level.
* Water daily.

Paragraphs in Ducktype are implicit and separated by blank lines. List items are introduced with an asterisk and a space.

This example creates a simple list element. Mallard actually has a more specific element for a list of steps: the steps element. You can use steps instead using the Ducktype block element notation.

= Planting Beans
  [topic]
@link[guide >index]

By the end of this page, you will be able to plant your magic
beans and nurture them into a bean sprout.

[steps]
* Dig a hole 5cm deep.
* Place your magic beans in the hole.
* Fill the hole with clean dirt and pat it level.
* Water daily.

We've seen paragraphs and lists, and gotten a glimpse of other block elements. Let's explore block elements further. Mallard provides a handful of semantic block elements for things like notes, figures, and code snippets. Ducktype allows you to use all of these elements with block annotations. Try adding a note to one of your pages:

[note]
This is a simple note with a single line of content.

Ducktype also allows you to nest content using indentation. To create a note with two paragraphs, indent both paragraphs. The amount of indentation doesn't matter, as long as you're consistent. We prefer two-space indentation though.

[note]
  This is a simple note and this is the first paragraph.

  This is another paragraph in that note.

Nesting isn't just limited to paragraphs. You can nest any block elements as deeply as you want. For example, you could add a list inside of a note.

[note]
  Remember the three virtues of a programmer:

  * Laziness
  * Impatience
  * Hubris

Earlier we added attributes to headers and informational elements. We can do the same thing with block elements by putting the attributes inside the square brackets.

[note style=tip]
  This is a tip. It will probably be styled differently.

Like type and xref, the style attribute is very common in Mallard, and so it gets a shorthand notation. Use a leading dot to indicate a style hint.

[note .tip]
  This is a tip. It will probably be styled differently.