Markdown Syntax

The docs are written in Markdown .mdx files.

For link guidance, see Links.

Inline Code

Use tick marks only for code literals, filenames, and directory paths.

• To mark text as inline code, use a pair of backticks: `code`.

Code Blocks

• Code blocks use syntax highlighting for the language as defined in the code fence. For TypeScript-specific code fences in tutorials, see Tutorial Runner.

• Type $ at the beginning of the command line. On the published doc, the prompt is stripped by the copy-to-clipboard action.

• Introduce the command and then add the command in a code fence:

To compile the TypeScript code into JavaScript:

```sh
$ npm run build
```

• To include the expected output of a command, add an introduction to the results, and then add the expected output in another code fence:

Try running this command again:

```sh
$ npm run build && node build/src/main.js
```

The expected output is:

```sh
> [email protected] build
> tsc

o1js loaded
state after init: 3
Shutting down
```

Use four backticks to preserve three backticks inside the code fence:

code

```

to renders as ```code```.

## Numbered steps

To generate an ordered list, start each step with `1.` so that each step automatically increments numbering. Auto-numbering is respected only when the content under a step is indented (2 or 4 spaces; in IDE such as VS Code, press the tab key). 

The indentation for numbered steps is required to position the content under each step and to keep the auto-numbering in step.

Tip: Use `npm run dev` to see [local doc updates during development](https://github.com/o1-labs/docs2/blob/main/README.md#how-to-see-your-local-doc-updates-during-development).

## Callouts

For general information and guidance on notice types, see [Notices](https://developers.google.com/style/notices).

When you decide to use a callout, use one of the following notice types and this [Callout syntax](https://docusaurus.io/docs/markdown-features/admonitions). 
  
* **Info** Use for "must know" information.
  
```markdown
:::info
Events and actions are not stored in the ledger and exist only on the transaction.
:::
```

* **Note** Use for general and "nice to know" information.
  
```markdown
:::note
Newly staked accounts incur a delay of 18 to 29 days before you start receiving rewards.
:::
```

* **Tip** Use for context-relevant, helpful information.

```markdown
:::tip
While Mina and its SDKs do support the memo field when sending a transaction, the recommended best practice is <u>do NOT require a memo for deposits</u>.
:::
```

* **Experimental** Use for zkApp experimental features and be sure to link to the [Experimental features](https://docs.minaprotocol.com/zkapps/experimental) page.

```markdown
:::experimental
The use of the ZkProgram API with recursion is experimental. This API may change. To learn more, see [Experimental Features](/zkapps/experimental).
:::
```

* **Caution** Use to provide critical information that a user can't reverse if they continue with the task, for example, to warn a user of data loss and there's a consequence they can't reverse.

```markdown
:::caution
- Mina APIs are still under construction, so these endpoints may change.
- By default, the GraphQL port is bound to localhost. Exposing the GraphQL API to the internet allows anyone to send Mina from the accounts known to the daemon.
:::
```

* **Danger** Use for security warnings. For example, where failure to take an action can result in a security vulnerability (for example, loss of funds or XSS attack). For example, "Always validate user-provided data to prevent XSS attacks." 

```markdown
:::danger
Use `assertNothing()` with caution. Using `assertNothing()` could cause security issues through unexpected behavior if used improperly. 
:::
```

## Markdown and JavaScript

The built-in Docusaurus support renders the JSX in Markdown `.mdx` files as React components. 

## Sidebar

To add docs, change the structure, or move docs in the navigation sidebar on the published docs website, update [sidebars.js](https://github.com/o1-labs/docs2/blob/main/sidebars.js).

All markdown files in the `/docs` directory are published. The entry in `sidebars.js` just controls how the page appears in the sidebar. To include a page in the docs, like [Experimental](https://docs.minaprotocol.com/zkapps/experimental), just omit it from `sidebars.js`.
In some situations, it makes sense to provide a full title on the page `o1js Overview` but retain a brief title in the sidebar. 

Frontmatter (preferred method of promoting content other than `title` to top of page)
`title: o1js FAQ`
`sidebar_label: FAQ`

Existing workaround May 2023 and earlier:
Before Berkeley hard fork, the goal was to show the Info (zkApp programmability not on Mina Mainnet, only deployed to Berkeley Testnet) as the first thing that's shown on the page:
use `hide_title: true` and rely on the `# Heading1` for the title

Without `hide_title: true`, the title is shown first with the Info box below it. 

In this case, the Markdown frontmatter defines the title for the sidebar and hides it on the page:

```
---
title: o1js Overview
hide_title: true
---
```

The first heading 1 in the content defines the sidebar text:

`# Overview`

## Adding images to docs

Add the .png or .jpg image file to the `/docs2/static/img` directory.

Use this syntax for the image and caption:

```markdown
<figure>
  <img
    src="/img/2_zkApps_Examples.jpg"
    alt="Example zkApp zero knowledge applications."
    width="85%"
  />
  <figcaption>
    zkApps are a great fit for applications that require proof that you have a
    secret without revealing it to anyone.
  </figcaption>
</figure>
```

### Docs home page

The source image for the docs home page is in `static/img/homepage/zkapp_developers.png`.

The content on the docs home page https://github.com/o1-labs/docs2/blob/main/docs/welcome.mdx is rendered from a React component.

## Adding files to docs

The [Mina Delegation Program Return Addresses](https://docs.google.com/spreadsheets/d/1Fm4XSS9Xu4eWAhpM06sdySUKvLClR5SculXfP5o5sSc/edit#gid=0) spreadsheet is the canonical source of the `Mina_Foundation_Addresses.csv` file that users are prompted to download in the [Mina Foundation Delegation Program](https://docs.minaprotocol.com/node-operators/foundation-delegation-program). 

Add the file to the `static` directory and then use this syntax to link to the file:

```markdown
[Mina Foundation addresses](/Mina_Foundation_Addresses.csv)
```

## Adding videos in docs

Developers can experience up to a 50% productivity boost when documentation is up-to-date, detailed, reliable, and comes in different formats (docs + blogs, videos, forums. Source: [State of the Octoverse 2021](https://octoverse.github.com/2021/). Consider adding videos!

The ResponsiveVideo component improves UX and SEO, provides an optimal viewing experience across different devices, and ensures our embedded YouTube videos scale properly and maintain a mobile-friendly interface. 

Easiest is to look at the Markdown syntax for working models, like [https://github.com/o1-labs/docs2/blob/main/docs/about-mina/what-are-zero-knowledge-proofs.mdx](https://github.com/o1-labs/docs2/blob/main/docs/about-mina/what-are-zero-knowledge-proofs.mdx) that embeds a video in  the [What are Zero-Knowledge Proofs?](https://docs.minaprotocol.com/about-mina/what-are-zero-knowledge-proofs) page.

1. On a computer, go to the YouTube video you want to embed.

2. Click **Share** > **Embed**. 

3. In the embed video frame, copy the `src="https://www.youtube.com/embed/xxx"` code fragment.

4. Add this import statement at the top of the .mdx file outside of the metadata blocks. Right after the last `---` is fine:

```
import ResponsiveVideo from '@site/src/components/common/ResponsiveVideo';
```

5. Add the video where you want it to appear on the doc page:

```
<ResponsiveVideo src="https://www.youtube.com/embed/xxx" />
```

PR for the ResponsiveVideo component https://github.com/o1-labs/docs2/pull/427/.