Skip to content

Markdown Syntax

Jump to bottom
Barrie Byron edited this page Mar 12, 2024 · 52 revisions

The docs are written in Markdown .mdx files.

For link guidance, see Links. For image guidance, see Images.

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
> 01-hello-world@0.1.0 build
> tsc

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

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

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.

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 _not-production-ready feature_ is experimental and this _API/feature/whatsits_ 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:

# zkApps Overview

Pro tip: Using a heading title like Overview is vague. Instead, make your heading unique to the docs to improve search results.

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, especially explainer videos that are not version-bound.

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.

The easiest way to link videos 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/.

Mina Docs

Clone this wiki locally