Code Snippets

To make code snippets in the documentation more "real" and robust, it is better to fetch them directly from the source files. The sources are located in other repositories, where they are built, run, and tested.

How it works

Snippet Sources

Snippet sources are defined in snippet_sources.ts. The snippet_sources.ts file is located at the documentation repository and has the following format:

export default [
  {
    src: 'https://raw.githubusercontent.com/hyperledger/iroha/iroha2-stable/MAINTAINERS.md',
    filename: 'iroha-maintainers-at-stable.md',
  },
  {
    src: './src/example_code/lorem.rs',
  },
]

src defines the source file location and could be either an HTTP(s) URI or a relative file path.
filename (optional) explicitly defines the local filename.

Fetching Snippets

Code snippets are fetched from the locations specified in snippet_sources.ts and written into the /src/snippets directory. There are two ways to fetch the snippets:

Automatically after dependencies were installed (i.e. pnpm install)
Manually by calling pnpm get-snippets

TIP

By default, snippets are deleted and reloaded each time pnpm get-snippets is called. For local development it might be more convenient to enable "lazy" behavior by calling pnpm get-snippets --force false.

Using Snippets in Markdown

Use Code Snippets feature in VitePress to include snippets into documentation:

Input

<<<@/snippets/lorem.rs

<<<@/snippets/lorem.rs#ipsum

Output

fn main() {
    // #region ipsum
    println!("Lorem ipsum");
    // #endregion ipsum
}

println!("Lorem ipsum");

Note that we included only the #ipsum code region, not the entire file. This feature is essential when it comes to including code from real source files into the documentation.

Example

Let's add a code snippet from Iroha JavaScript SDK. For example, this one: /packages/docs-recipes/src/1.client-install.ts.

First, get a permalink to the file. Open the file on GitHub and click Raw button to get the link. For example: https://raw.githubusercontent.com/hyperledger/iroha-javascript/e300886e76c777776efad1e2f5cb245bfb8ed02e/packages/docs-recipes/src/1.client-install.ts

Define the new snippet in the Snippet Sources:

export default [
  /// ...

  {
    src: 'https://raw.githubusercontent.com/hyperledger/iroha-javascript/e300886e76c777776efad1e2f5cb245bfb8ed02e/packages/docs-recipes/src/1.client-install.ts',
    filename: 'js-sdk-1-client-install.ts',
  },
]

TIP

Since snippet_sources.ts is a TypeScript file, we can use all scripting features in it. Meanwhile, we are trying to keep it as simple as possible, so even the one who doesn't know TypeScript at all could edit it.

However, we use a bit of scripting. We defined several constants with git revisions from multiple repositories:

const IROHA_REV_STABLE = 'c4af68c4f7959b154eb5380aa93c894e2e63fe4e'

const IROHA_REV_DEV = '...'

const IROHA_JS_REV = '...'

Then we use them in links to snippet sources in place of git revisions, like this:

export default [
  // ...

  {
    src: `https://raw.githubusercontent.com/hyperledger/iroha/${IROHA_REV_STABLE}/MAINTAINERS.md`,
    //                                                        ^^^^^^^^^^^^^^^^^^^
    filename: 'iroha-maintainers-at-stable.md',
  },
]

It helps us to reduce repetitions and keep sources clean.

Include the snippet in any Markdown file in the documentation as follows:

Input

<<<@/snippets/js-sdk-1-client-install.ts

Output

import { crypto } from '@iroha2/crypto-target-node'
import { setCrypto } from '@iroha2/client'

setCrypto(crypto)

Code Snippets ​

How it works ​

Snippet Sources ​

Fetching Snippets ​

Using Snippets in Markdown ​

Example ​