build details
0 errors, 17 warnings, 11 tasks

Show: section status errors & todos local changes recent changes last change in-page changes feedback controls

Basic Markduck guide

✎

Modified 2019-09-22 by Andrea Censi

The Duckiebooks are written in Markduck, a Markdown dialect.

It supports many features that make it possible to create publication-worthy materials.

Markdown

✎

Modified 2018-06-02 by Andrea Censi

The Duckiebook are written in a Markdown dialect.

A tutorial on Markdown.

Comments

✎

Modified 2020-09-02 by Andrea Censi

You can insert comments using the HTML syntax for comments: any text between “<!–” and “–>” is ignored.

# My section

<!-- this text is ignored -->

Let's start by...

Variables in command lines and command output

✎

Modified 2018-06-02 by Andrea Censi

Use the syntax “![name]” for describing the variables in the code.

For example, to obtain:

$ ssh robot name.local

Use the following:

For example, to obtain:

    $ ssh ![robot name].local

Make sure to quote (with 4 spaces) all command lines. Otherwise, the dollar symbol confuses the LaTeX interpreter.

Character escapes

✎

Modified 2019-10-01 by Rohit Suri

Use the string &#36; to write the dollar symbol $, otherwise it gets confused with LaTeX math materials. Also notice that you should probably use “USD” to refer to U.S. dollars.

Other symbols to escape are shown in Table 1.1.

Symbols to escape
use &#36; instead of $
use &#96; instead of `
use &lt; instead of <
use &gt; instead of >

Keyboard keys

✎

Modified 2018-06-02 by Andrea Censi

Use the kbd element for keystrokes.

For example, to obtain:

Press a then Ctrl-C.

use the following:

Press <kbd>a</kbd> then <kbd>Ctrl</kbd>-<kbd>C</kbd>.

Figures

✎

Modified 2018-06-02 by Andrea Censi

To create a figure, use the element figure:

<figure>
    <figcaption>Hello</figcaption>
    <img style='width:8em' src="duckietown-logo-transparent.png"/>
</figure>
Hello

More attributes

✎

Modified 2018-06-02 by Andrea Censi

Use class="caption-left" to have the caption show up on the left rather than on the bottom:

<figure class="caption-left">
    <figcaption>Hello</figcaption>
    <img style='width:8em' src="duckietown-logo-transparent.png"/>
</figure>
Hello

Subfigures

✎

Modified 2018-06-02 by Andrea Censi

You can create subfigures by nesting figure elements:

<figure>  
    <figcaption>Main caption</figcaption>
    <figure>
        <figcaption>Hello</figcaption>
        <img style='width:8em' src="duckietown-logo-transparent.png"/>
    </figure>
    <figure>  
        <figcaption>second</figcaption>
        <img style='width:8em' src="duckietown-logo-transparent.png"/>
    </figure>
</figure>
Hello
second
Main caption

By default, they are displayed one per block. To make them flow horizontally, add class="flow-subfigures" to the external figure:

<figure class="flow-subfigures">  
    <figcaption>Main caption</figcaption>
    <figure>
        <figcaption>Hello</figcaption>
        <img style='width:8em' src="duckietown-logo-transparent.png"/>
    </figure>
    <figure>  
        <figcaption>second</figcaption>
        <img style='width:8em' src="duckietown-logo-transparent.png"/>
    </figure>
</figure>
Hello
second
Main caption

For any element, adding an attribute called figure-id with value fig:figure ID or tab:table ID will create a figure that wraps the element.

Shortcut for tables

✎

Modified 2020-09-02 by Andrea Censi

The shortcuts col2, col3, col4, col5 are expanded in tables with 2, 3, 4 or 5 columns.

The following code:

<col2 figure-id="tab:mytable" figure-caption="My table">
    <span>A</span>
    <span>B</span>
    <span>C</span>
    <span>D</span>
</col2>

gives the following result:

My table
A B
C D

labels-row1 and labels-row1

✎

Modified 2018-06-02 by Andrea Censi

Use the classes labels-row1 and labels-row1 to make pretty tables like the following.

labels-row1: the first row is the headers.

labels-col1: the first column is the headers.

Using class="labels-col1"
header A B C 1
header D E F 2
header G H I 3
Using class="labels-row1"
header A header B header C
D E F
G H I
1 2 3

Linking to documentation

✎

Modified 2018-06-02 by Andrea Censi

Establishing names of headers

✎

Modified 2020-09-02 by Andrea Censi

You give IDs to headers using the format:

### header title {#topic ID}

For example, for this subsection, we have used:

### Establishing names of headers {#establishing}

With this, we have given this header the ID “establishing”.

By convention, we use consistently dashes rather than underscores. For example, instead of using the ID #my_cool_section, use #my-cool-section.

How to name IDs - and why it’s not automated

✎

Modified 2020-09-02 by Andrea Censi

Some time ago, if there was a section called

## My section

then it would be assigned the ID “my-section”.

This behavior has been removed, for several reasons.

One is that if you don’t see the ID then you will be tempted to just change the name:

## My better section

and silently the ID will be changed to “my-better-section” and all the previous links will be invalidated.

The current behavior is to generate an ugly link like “autoid-209u31j”.

This will make it clear that you cannot link using the PURL if you don’t assign an ID.

Also, I would like to clarify that all IDs are global (so it’s easy to link stuff, without thinking about namespaces, etc.).

Therefore, please choose descriptive IDs, with at least two IDs.

E.g. if you make a section called

## Localization  {#localization}

that’s certainly a no-no, because “localization” is too generic.

## Localization {#intro-localization}

Also note that you don’t need to add IDs to everything, only the things that people could link to. (e.g. not subsubsections)

Linking from the documentation to the documentation

✎

Modified 2020-09-02 by Andrea Censi

You can use the syntax:

[](#topic ID)

to refer to the header.

You can also use some slightly more complex syntax that also allows to link to only the name, only the number or both (Table 1.5).

Linking to other books

✎

Modified 2021-03-25 by Liam Paull

It is possible to link from one book to another.

The syntax is a slightly extended syntax. Instead of using something like 

See this [interesting section](#interesting-section).

You need to use add +other-book-id before the #:

See this [interesting section in another book](+other-book-id#interesting-section).

To find out what is the book ID, go to the current index of all the books, which, for daffy, is https://docs.duckietown.org/daffy/. Go to the book you want to link, and note the URL. The book ID is the part after daffy.

For example, this book is published at 

https://docs.duckietown.org/daffy/duckumentation/out/index.html

The book ID is duckumentation.

To link to the entire book, use something like +BOOKID#book. (By convention, each book will have the main header assigned the header #book:book.)

Here is a list of some of the books as of August 2020:

(For developers) How to update the list of books that can be crossreferenced.

✎

Modified 2020-09-02 by Andrea Censi

The dictionary between book ID and URL is maintained in the repo docs-build in the file books.crossref.yaml. When a new book is added, the list needs to be updated and the image duckietown/docs-build be updated.