Skip to main content

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, 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} title=snippet.py@ti.kerneldef 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:

snippet.py
@ti.kerneldef 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 1Some Table Col 2
Val1Val4
Val2Val5
Val3Val6
TIP

It's worth mentioning that Tables Generator 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.

We follow the best practices suggested by Docusaurus to cross-reference other documents, so to link to sections in other articles, please use the following relative-path based syntax, which is docs-versioning and IDE/Github friendly:

4. Centered text block#

To make a text or image block centered, use:

<center>
Centered Text Block!
</center>

Centered Text Block!

NOTE

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

6. Custom containers#

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

:::tipThis is a tip without title!:::
tip

This is a tip without title!

:::tipThis is a tip with a title!:::
TITLE

This is a tip with a title!

:::noteThis is a note!:::
note

This is a note!

:::cautionThis is a warning!:::
WARNING

This is a warning!

:::danger DANGERThis is a danger!:::
DANGER

This is a danger!

7. Code groups#

You could also insert tab-based code groups:

import Tabs from '@theme/Tabs';import TabItem from '@theme/TabItem';
<Tabs  defaultValue="apple"  values={[    {label: 'Apple', value: 'apple'},    {label: 'Orange', value: 'orange'},    {label: 'Banana', value: 'banana'},  ]}>  <TabItem value="apple">This is an apple ๐ŸŽ</TabItem>  <TabItem value="orange">This is an orange ๐ŸŠ</TabItem>  <TabItem value="banana">This is a banana ๐ŸŒ</TabItem></Tabs>
This is an apple ๐ŸŽ

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 footnote1. (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 ^[I'm another footnote] (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)

kernel

10. Insert Table of Contents (ToC)#

You could use:

import TOCInline from '@theme/TOCInline';
<TOCInline toc={toc} />

to insert in-line ToC:


  1. I'm a footnote!โ†ฉ