Prerequisites

• clone motoko and motoko-base to your machine

• install nix following the instructions for your system

• enable nix cache to get all dependencies prebuilt

  nix-env -iA cachix -f <https://cachix.org/api/v1/install>
  cachix use ic-hs-test
  

Adding documentation

• head into motoko-base/src

• pick one of the base libraries you’d like to add examples for, e.g. Trie.mo

• within that library, start adding code snippets to the docstrings like the following

  /// Example:
  /// ```motoko name=initialize
  /// import Buffer "mo:base/Buffer";
  ///
  /// let buffer = Buffer.Buffer<Nat>(3); // Creates a new Buffer
  /// ```
  

• note that the following rules apply

  We wrap Docusaurus's module CodeBlock/Content/String to process Motoko code blocks with interpreter. To enable this feature, add the following flags for code blocks:

  • motoko adds a Run button
  • motoko run adds a Run button and display the result
  • motoko no-repl syntax-highlighting only.
  • motoko name=filename saves the code as filename.mo so that it can be imported or referenced from another code block. An absent filename defaults to stdin.
  • motoko include=f1,f2 run f1.mo, f2.mobefore running the current code, equivalent tomoc -i f1.mo f2.mo current_code.mo. It will fetch the updated code each time we click run. Note that if the code import "f1" but doesn't use include_f1, the code won't be updated until we click the run button for f1.mo.

  The config flags can be used in any order with any combinations, e.g. motoko run name=main include=f1,f2

• this means that the above code Snippet 1 can be included in other snippets. this makes the snippets more concise and clearer, as you don’t have to run initalization code over and over to create a Buffer for example

  /// Example:
  /// ```motoko include=initialize
  ///
  /// buffer.add(0); // add 0 to buffer
  /// buffer.add(1);
  /// buffer.add(2);
  /// buffer.add(3); // causes underlying array to increase in capacity
  /// Buffer.toArray(buffer)
  /// ```
  

Building the docs

• head into motoko and run the following command. this will start a nix shell (first time takes ages)

  nix-shell
  

• in nix-shell, export an environment variable MOTOKO_BASE that points to the src folder of the motoko-base repository on your machine (e.g. MOTOKO_BASE=~/projects/motoko-base/src).

• cd into motoko/doc and run

  make preview
  

• run the following command from within motoko/doc whenever you want to affect the live preview by regenerating the markdown from the base source files. make sure you’re inside the nix-shell and the MOTOKO_BASE env variable points to the correct folder.

  make -C ../src mo-doc # only needed for the first time
  make base
  

• to avoid running the previous step over and over manually after adding changes, consider running the following command in a separate terminal from within motoko/doc

  fswatch ../../motoko-base/src | xargs -n1 -I{} make base