Skip to content

Markdown Syntax

Jump to bottom
Barrie Byron edited this page Jul 19, 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 Mina zkApp CLI makes it easy to follow recommended best practices by providing project scaffolding, including dependencies such as SnarkyJS, 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)

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

Use this Callout syntax.

You can update the callout headline, but not the callout icon.

  • 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

  • Info Use for limitations and "must know" information.

    info

  • Note Use for general and "nice to know" information.

    note

  • Tip Do not use, mostly because of the green color.

    tip

  • Caution Do not use.

    caution

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.

In some situations, it makes sense to provide a full title on the page SnarkyJS Overview but retain a brief title in the sidebar.

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

Existing workaround May 2023 and earlier: Before Berkely hard fork, the goal was to show the Info (zkApp programmability not on 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: SnarkyJS 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:

    image

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

    image

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>

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 working models like https://github.com/o1-labs/docs2/blob/main/docs/about-mina/what-are-zero-knowledge-proofs.mdx for the What are Zero-Knowledge Proofs? page.

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

  2. Click Share.

  3. Click the Copy button to copy the link to the video.

  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 responsive iFrame where you want your video in the doc page:
<ResponsiveVideo src="your_embed_link_here" />

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

https://discord.gg/minaprotocol

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.

    Untitled

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