Documentation Writing Guide

Thank you for your contribution! This article briefly introduces syntax that will help you write documentation on this website. Note, the documentation is written in an extended version of Markdown (opens new window), so for most of the time, you don't need special syntax besides the basic markdown syntax.

1. Insert code blocks

This site supports inserting code blocks with highlighted lines, for examples, the following:

```python {1-2,4,6}
@ti.kernel
def paint(t: float):
    for i, j in pixels:  # Parallized over all pixels
        c = ti.Vector([-0.8, ti.cos(t) * 0.2])
        z = ti.Vector([i / n - 1, j / n - 0.5]) * 2
        iterations = 0
        while z.norm() < 20 and iterations < 50:
            z = complex_sqr(z) + c
            iterations += 1
        pixels[i, j] = 1 - iterations * 0.02
```

will result in a code block like:

@ti.kernel
def paint(t: float):
    for i, j in pixels:  # Parallized over all pixels
        c = ti.Vector([-0.8, ti.cos(t) * 0.2])
        z = ti.Vector([i / n - 1, j / n - 0.5]) * 2
        iterations = 0
        while z.norm() < 20 and iterations < 50:
            z = complex_sqr(z) + c
            iterations += 1
        pixels[i, j] = 1 - iterations * 0.02

2. Insert tables

| Some Table Col 1 | Some Table Col 2 |
| :--------------: | :--------------: |
|       Val1       |       Val4       |
|       Val2       |       Val5       |
|       Val3       |       Val6       |

Some Table Col 1	Some Table Col 2
Val1	Val4
Val2	Val5
Val3	Val6

TIP

It's worth mentioning that Tables Generator (opens new window) is a great tool for generating and re-formatting markdown tables.

3. Cross-reference and anchor

To link to another section within the same article, you would use [Return to ## 1. Insert code blocks](#_1-insert-code-blocks): Return to ## 1. Insert code blocks.

To link to sections in other articles, use the following syntax (note the relative paths):

• [Return to Contribution guidelines](./contributor_guide): Return to Contribution guidelines
• [Return to Contribution guidelines](./contributor_guide.md): Return to Contribution guidelines
• [Return to The Documentation](../docs/develop/documentation/overview/hello.md#portability): Return to The Documentation

4. Centered text block

To make a text block centered, use:

<center>
Centered Text Block!
</center>

Centered Text Block!

NOTE

For images, you HAVE TO insert blank lines to make them work:

<center>

![](./some_pic.png)

</center>

5. Text with color backgorund

You could use the following to highlight your text:

<span id="inline-blue"> Text with blue background </span>,
<span id="inline-purple"> Text with purple background </span>,
<span id="inline-yellow"> Text with yellow background </span>,
<span id="inline-green"> Text with green background </span>

Text with blue background , Text with purple background , Text with yellow background , Text with green background

You could also use the markdown-it syntax ==My text== to achieve similar result: My text.

6. Custom containers

As we already saw in this guide several places, we could add custom containers:

::: tip
This is a tip without title!
:::

TIP

This is a tip without title!

::: tip
This is a tip with a title!
:::

TITLE

This is a tip with a title!

::: note
This is a note!
:::

NOTE

This is a note!

::: warning
This is a warning!
:::

WARNING

This is a warning!

::: danger DANGER
This is a danger!
:::

DANGER

This is a danger!

::: details SUMMARY
Details by default are hidden!
:::

SUMMARY

Details by default are hidden!

7. Code groups

You could also insert tab-based code groups:

print("Hello World")

#include<iostream>

using namespace std;

int main()
{
    // prints hello world
    cout<<"Hello World";

    return 0;
}

// Make sure to add code blocks to your code group

8. Footnotes

It is important to cite the references, to do so, use the markdown-it's footnotes syntax:

This sentence has a footnote[^1]. (See footnote at the bottom of this guide.)

[^1]: I'm a footnote!

which results in:

---

This sentence has a footnote^[1]. (See footnote at the bottom of this guide.)

---

We could also write in-line footnotes, which is much easier to write without counting back and forth:

This sentence has another footnote ^[I'm another footnote] (See footnote at the bottom of this page.)

which has the same effect:

---

This sentence has another footnote ^[2] (See footnote at the bottom of this page.)

---

9. Insert images

Insert images is as straight-forward as using the ordinary markdown syntax:

![kernel](./life_of_kernel_lowres.jpg)

you could also use syntax like the following to resize:

![kernel](./life_of_kernel_lowres.jpg =500x300)

10. Insert Table of Contents (ToC)

You could use:

[[toc]]

to insert in-line ToC:

• 1. Insert code blocks
• 2. Insert tables
• 3. Cross-reference and anchor
• 4. Centered text block
• 5. Text with color backgorund
• 6. Custom containers
• 7. Code groups
• 8. Footnotes
• 9. Insert images
• 10. Insert Table of Contents (ToC)
• 11. Insert badges

11. Insert badges

You could add a variety of badges along with the text:

<Badge text="hello!" type="tip"/>
<Badge text="hello!" type="tip" vertical="middle"/>

hello! hello!

<Badge text="hello!" type="warning"/>
<Badge text="hello!" type="warning" vertical="middle"/>

hello! hello!

<Badge text="hello!" type="error"/>
<Badge text="hello!" type="error" vertical="middle"/>

hello! hello!

---

1. I'm a footnote! ↩︎

2. I'm another footnote ↩︎