Skip to main content

Writing Project Documentation

This guide will help you create markdown documentation for your projects using our system's supported features.

Directory Structure​

Documentation can be placed in one of two locations:

  • For project-specific documentation: www/projects/<project_id>/docs
  • For common documentation: www/docs

You can organize documentation into directories as needed.

Order in the Index Tree​

Items in the index tree on the left can be ordered using number prefixes on file or directory names. These prefixes are stripped out and do not appear in the labels.

For example:

00-first.md
01-second
02-third.md

Markdown Features​

Headings​

Use # for headings. The number of # symbols indicates the level of the heading.

# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6

Headers and Labels​

The items appear in the index tree with the top-level header as the label.

Header Anchors​

Anchors follow the GitHub style. Links can be created to specific sections within the same document or to other documents. Headers are automatically converted to anchor links by converting to lowercase, replacing spaces with hyphens (-), and removing special characters. Example:

## Section Title

The resulting anchor link will be #section-title.

Custom anchors can be set using the following syntax:

## Section Title \{#custom-anchor}

Paragraphs​

Paragraphs are separated by a blank line.

This is the first paragraph.

This is the second paragraph.

Line Breaks​

End a line with two or more spaces to create a line break.

This is the first line.
This is the second line.

Emphasis​

Use * or _ for emphasis.

*Italic* or _Italic_

**Bold** or __Bold__

***Bold and Italic*** or ___Bold and Italic___

Blockquotes​

Use > for blockquotes. You can nest them by adding additional > symbols.

> This is a blockquote.
>> Nested blockquote.

This is a blockquote

Nested blockquote

Lists​

Unordered Lists​

Use -, *, or + for unordered lists.

- Item 1
- Item 2
  - Subitem 1
  - Subitem 2

Ordered Lists​

Use numbers followed by a period for ordered lists.

1. First item
2. Second item
   1. Subitem 1
   2. Subitem 2

Tables​

Use pipes (|) and hyphens (-) to create tables.

Example:

| Header 1 | Header 2 |
|----------|----------|
| Row 1    | Row 1    |
| Row 2    | Row 2    |
Header 1Header 2
Row 1Row 1
Row 2Row 2

Code​

Inline Code​

Use backticks for inline code.

Here is some `inline code`.

Code Blocks​

Use triple backticks for code blocks.

```
Code block
```

Horizontal Rules​

Use three or more -, *, or _ for horizontal rules.

---
***
___

Use [text](url) for links.

[OpenAI](https://www.openai.com)

Relative links can be used to link to other files within the documentation.

[Link to another document](./another-document.md)

Anchor links can be used to link to specific sections within the same document.

[Link to section](#section-title)

or in another document.

[Link to section](./another-document.md#section-title)

Images​

Use ![alt text](url) for images.

![HSYCO Logo](https://www.hsyco.com/logo.jpg)

Escaping Characters​

Use a backslash to escape special characters.

\*This text is not italicized\*

Characters that can be excaped include: *, _, {, }, [, ], (, ), #, +, -, ., !, and \.

Extended Features​

Admonitions​

You can include admonitions to highlight important information.

Example:

:::note
This is a note.
:::
note

This is a note.

Supported admonition types: note, tip, info, caution, danger.

Example:

:::tip
This is a tip.
:::
tip

This is a tip.

Custom Titles​

Admonitions can also have custom titles.

Example:

:::note[My Custom Title]
This is a note with a custom title.
:::
My Custom Title

This is a note with a custom title

Meta Data​

At the beginning of each markdown file, you can include meta configuration options. Here are the supported options:

  • sidebar_position: <number> - Defines the position in the sidebar.
  • toc_min_heading_level: <number> - Minimum heading level to include in the table of contents.
  • toc_max_heading_level: <number> - Maximum heading level to include in the table of contents.
  • sidebar_class_name: hidden - Hides the item from the sidebar.

Example:

---
sidebar_position: 1
toc_min_heading_level: 2
toc_max_heading_level: 4
sidebar_class_name: hidden
---