Documentation is written in Markdown and is located in the pages
directory. Additionally this Markdown uses syntax extensions provided by
MarkDoc. These extensions allow the creation of custom
components, such as code tabs, notes, and flow diagrams, all from within the
Markdown file.
Nodes are elements that Markdoc inherits from Markdown, specifically the CommonMark specification. Markdoc nodes enable you to customize how your document renders without using any custom syntax. This consists of items such as code fences and tables. We can extend these nodes to add additional functionality with attributes.
Tags are the main syntactic extension that Markdoc adds
on top of Markdown. Each tag is enclosed with {% and %} and includes the tag
name, attributes, and content body. Tags allow for creating custom components
that can be used in the documentation.
Updating Navigation is done by editing the
/data/*.ts files.
Code fences are a way to show blocks of code in a visually clear and distinct way. When you use code fences, you can also specify which programming language the code is written in, and this helps to display it with appropriate syntax highlighting, which makes it easier to read and understand. To specify the programming language, you simply add the name of the language right after the opening code fence.
| Attribute | Description |
|---|---|
| title | The title of the code block. |
| addMode | Whether or not to automatically add mode = 1 to the code block when viewing Slice1 documentation. Can be either true or false Default is false. |
```python title="hello.py"
def hello(name):
print("Hello, " + name)
``````slice addMode=true
module Foo
interface Bar {}
```Links are a way to reference other pages or external resources. Links can be to other pages within the documentation site, or to external resources such as GitHub or of the API reference. Links can be created by using the Markdown link syntax.
API reference links are links to the API reference. These links have a special
shorthand syntax that allows you to link to a specific class or method. The
syntax for these links is <language>:<class-name>
[ClientConnection](csharp:IceRpc.ClientConnection) will link to the page
<https://docs.icerpc.dev/api/csharp/api/IceRpc.ClientConnection.html>The callout tag is used to create a callout box. The callout tag supports a
type attribute that can be set to either note or danger. The type
attribute is used to set the color of the callout box and icon used. Any content
within the callout tag will be placed inside the callout box.
| Attribute | Description |
|---|---|
| type | The type of callout. Can be either note or danger. Default is note. |
{% callout %}
This is an note callout
{% /callout %}{% callout type="danger" %}
This is a danger callout
{% /callout %}The side-by-side tag is used to create columns of content that are
side-by-side. The content is split by a vertical divider. The first item in the
content is placed in the left column, and the second item is placed in the right
column. In the below example, the python codeblock would be placed in the left
column while the text would be placed in the right column.
| Attribute | Description |
|---|---|
| weighted | The column that should have more content. Can be either left or right. Default is left. |
| alignment | The alignment of the content in the columns. Can be either top or center. Default is center. |
{% side-by-side %}
```python
def hello(name):
print("I will be on the left")
```
I will also be on the left
I will be on the right
{% /side-by-side %}{% side-by-side weighted="right" %}
```python
def hello(name):
print("I will be on the left")
```
I will also be on the right
I will be on the right
{% /side-by-side %}{% side-by-side alignment="top" %}
```python
def hello(name):
print("I will be on the left")
print("I will be on the left")
print("I will be on the left")
print("I will be on the left")
```
I will be on the right
{% /side-by-side %}The divider tag is used to create a horizontal divider. This is useful for
breaking up content into sections.
Lorem ipsum dolor sit amet.
{% divider /%}
Lorem ipsum dolor sit amet.The grid tag is used to create a grid of content. It is primarily intended to be used with the mini-card tag.
| Attribute | Description |
|---|---|
| columns | The number of columns the grid could have, defaults to 3. (On mobile will always be 1) |
{% grid columns=2 %}
{% mini-card title="Foo" description="..." href="/foo" /%}
{% mini-card title="Bar" description="..." href="/bar" /%}
{% mini-card title="Fizz" description="..." href="/fizz" /%}
{% mini-card title="Buzz" description="..." href="/buzz" /%}
{% grid %}The mini-card tag is used to create a mini card. Mini cards are used in the grid tag. They are small cards with
a title, description, and link.
| Attribute | Description |
|---|---|
| title | The title of the mini card. |
| description | The description of the mini card. |
| href | The href used when clicking the mini card |
See the grid tag for an example of how to use the mini-card tag.
The light-mode tag is used to render content that should only be visible in light mode.
{% light-mode %}
This content will only be visible in light mode
{% /light-mode %}The dark-mode tag is used to render content that should only be visible in dark mode.
{% dark-mode %}
This content will only be visible in dark mode
{% /dark-mode %}The hierarchy of the side navigation is defined in /data/. Each top navigation
item has a corresponding file, getting-started-data.ts, icerpc-data.ts,
etc., with Slice having two files corresponding to which Slice
mode was selected. These files export an array that defines the pages and
their order in the sidebar. The values in the arrays are either SideBarLink or
SideBarCategory types.
For example, the following values define two SideBarLink objects, one with the
title Overview that links to the /getting-started/index.md page, and
another called Foo that links to the /getting-started/foo.md page.
This generates the sidebar for the Getting Started top navigation item.
export const gettingStartedData: SideBarSourceType[] = [
{
title: 'Overview',
path: `${GETTING_STARTED_BASE_URL}/`
},
{
title: 'Foo',
path: `${GETTING_STARTED_BASE_URL}/foo/`
},
...
]In addition to defining the pages in the sidebar, you can also use
SideBarCategory to define a category that contains a list of SideBarLink
objects.
The below array defines a SideBarCategory object with the title
Getting Started that contains a link to the "What is IceRPC?" page.
export const gettingStartedData: SideBarSourceType[] = [
{
title: 'Overview',
path: `${GETTING_STARTED_BASE_URL}/`
},
{
title: 'Getting started',
links: [
{
title: 'What is IceRPC?',
path: `${GETTING_STARTED_BASE_URL}/what-is-icerpc/`
},
...
]
}
...
]