The KILT Documentation website is built using Docusaurus 3, a modern static website generator.

Hosted at https://docs.kilt.io

yarn install

yarn start

This command starts a local development server and open up a browser window. Most changes are reflected live without having to restart the server.

yarn build

This command generates static content into the build directory and can be served using any static contents hosting service.

yarn test [dapp,workshop,core,staking]

Tests for code examples are located at code_examples. If possible code for new sections should be added to the sdk_examples project as a subcommand. When a subcommand is added, it also needs to be added to the test setup so that it will get executed.

To add a code example that is executed and tested, add the file to one of the code sections. Depending on where the code example is used, the code has to be put into a different section in the code_examples folder.

• Anything in the SDK section -> code_examples/sdk_examples/src/core_features/...
• The workshop -> code_examples/sdk_examples/src/workshop/...
• dApp examples -> code_examples/sdk_examples/src/dapp/...
• The Staking guide -> code_examples/sdk_examples/src/staking/...
• ➕ Add sections where you see fit

When writing code examples make sure that the script is as self explaining as possible.

• 👶 Easy to understand
  • If possible don't import helper functions that are not part of the SDK or polkadot-js
  • Ensure that there is no magic happening
  • Import SDK like this import * as Kilt from '@kiltprotocol/sdk-js' which avoids big import statements
• ♻️ Reusable
  • Make sure the code could be copy pasted and would run with little effort in a different environment
• 🎯 Concise
  • Only show what is relevant for the text you are writing
  • Prerequisites and setup should be done as much as possible outside of the code
    • Always link to other guides that explain the setup (e.g. DID creation, ...)
  • The code example should be wrapped in a function and anything that needs to be setup should be passed as parameters
• 🧪 Tested
  • Your code should be executed (call the function in one of the index.ts or test.ts files)
  • If possible return something that could be checked to ensure that the function executed successfully

There are three options to include code into markdown files, SnippetBlock, TsJsSnippet and TsJsBlock.

TsJsBlock is the preferred option to display code since it shows the whole file and transpiles the typescript code to JavaScript. The reader can than choose to either read the TS or JS code. TsJsBlock can be used like this:

import TsJsBlock from '@site/src/components/TsJsBlock';

import FullDidSimple from '!!raw-loader!@site/code_examples/sdk_examples/src/core_features/did/04_full_did_simple.ts';


# This is a markdown file

We imported `TsJsBlock` and the content `FullDidSimple` in the top of the file.

<TsJsBlock>
  {FullDidSimple}
</TsJsBlock>

Use TsJsSnippet and SnippetBlock if you only want to present the content of a function. These components will look for a main-function in your code and only show the content of that function. This is suitable for very short examples, usually only a few lines. Since imports and the function signature is hidden, this code can become harder to understand and reuse.

import SnippetBlock from '@site/src/components/SnippetBlock';
import TsJsSnippet from '@site/src/components/TsJsSnippet';

import Connect from '!!raw-loader!@site/code_examples/sdk_examples/src/core_features/getting_started/02_connect.ts';
import FetchEndpointData from '!!raw-loader!@site/code_examples/sdk_examples/src/core_features/getting_started/05_fetch_endpoint_data.ts';

# This is a markdown file

We imported `SnippetBlock` and the content `Connect` in the top of the file.

<SnippetBlock
  className="language-ts"
  dropTail="1"
>
  {Connect}
</SnippetBlock>

A `TsJsSnippet` is preferred since it automatically generates JavaScript examples.

<TsJsSnippet dropTail="1">
  {FetchEndpointData}
</TsJsSnippet>

This code is automatically deployed when pushed to master using AWS Amplify.