Skip to content

Markdown Syntax

Jump to bottom
Barrie Byron edited this page Oct 26, 2023 · 52 revisions

The docs are written in Markdown .mdx files.

Links

Use short descriptive link text that helps provide context for the material that you're linking to. For example, links to external URLs:

The zkApp CLI makes it easy to follow recommended best practices by providing project scaffolding, including dependencies such as o1js, a test framework [Jest](https://jestjs.io/), code auto-formatting [Prettier](https://prettier.io/
), linting [ES Lint](https://eslint.org/), and more.

Syntax for linking to other doc pages:

See [how zkApps work](/zkapps/how-zkapps-work), [how to write a zkApp](/zkapps/how-to-write-a-zkapp), and [zkApps for Ethereum Developers](/zkapps/zkapps-for-ethereum-developers)

Syntax for linking to headings within a doc page:

See [Install Mina zkApp CLI](/zkapps/how-to-write-a-zkapp#install-mina-zkapp-cli)

Syntax for linking to GitHub directories and files:

  • Use tree for directories: [examples/zkapps/06-offchain-storage/contracts](https://github.com/o1-labs/docs2/tree/main/examples/zkapps/06-offchain-storage/offchain-storage-zkapp/contracts)
  • Use blob for files: [src/main.ts](https://github.com/o1-labs/docs2/blob/main/examples/zkapps/06-offchain-storage/offchain-storage-zkapp/contracts/src/main.ts)

Markdown links work in different ways on our docs site. Although you can use a relative path, the preferred syntax is to use the file path after the base docs site URL.

Select the heading on the docs page to display the direct link in the web browser address bar. Copy the link after https://docs.minaprotocol.com/.

Callouts

For general information and guidance on notice types, see Notices.

When you decide to use a callout, use one of the following notice types and this Callout syntax.

  • Info Use for "must know" information.
:::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.
:::note
Newly staked accounts incur a delay of 18 to 29 days before you start receiving rewards.
:::
  • Tip Use for context-relevant, helpful information.
:::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 page.
:::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.
:::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."
:::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.

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, 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

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
```

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:

<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 spreadsheet is the canonical source of the Mina_Foundation_Addresses.csv file that users are prompted to download in the Mina Foundation Delegation Program.

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

[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. 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 that embeds a video in the 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';
  1. 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/.

Adding links to Mina Protocol Discord

Best practices for sharing links to Mina Protocol Discord.

Invite links to Mina Protocol Discord

The official invite link for the Mina Protocol Discord is under review (MF Sherry and Andrea). Tracking is on https://bit.ly/MinaDiscord so we want to change docs links from:

[Mina Protocol Discord](https://discord.gg/minaprotocol)

To:

[Mina Protocol Discord](https://bit.ly/MinaDiscord)

This URL resolves to https://discord.com/invite/minaprotocol.

Channel-specific links

In the Discord app and [Discord.com/app](http://discord.com/app) web browser UI:

  • Right-click a channel and select Copy Link.

The resulting shares of channel references are more uniform to share in the docs, Tweets, and other content.

Using these channel URLs has several nifty benefits:

Add the link only to the channel name text as shown in the following example:

Example for #zkapps-developers

Participate in the [#zkapps-developers](https://discord.com/channels/484437221055922177/915745847692636181) channel on Mina Protocol Discord.

Popular channels

[#announcements](https://discord.com/channels/484437221055922177/601171209287368715)
[#delegation-program](https://discord.com/channels/484437221055922177/808895957978447882)
[#grants](https://discord.com/channels/484437221055922177/727960609832042607) 
[#ledger-hardware](https://discord.com/channels/484437221055922177/733755408161833040)
[#mentor-nodes](https://discord.com/channels/484437221055922177/746316198806814760) 
[#mainnet-block-producers](https://discord.com/channels/484437221055922177/799597981762453535) 
[#security](https://discord.com/channels/484437221055922177/799979001585336331) 
[#zkapps-developers](https://discord.com/channels/484437221055922177/915745847692636181) 
[#zkapps-general](https://discord.com/channels/484437221055922177/910549624413102100)

Mina Docs

Clone this wiki locally