Skip to main content

Code Blocks

This page describes how to format code blocks in documentation.

tip

When formatting code blocks, be sure to include the language after the first three backticks of the code block. This will help ensure that the syntax highlightingh for the code block will work propoerly when the page is rendered in the static site generator.

For details on which languages are supported, see the list of languages that Docusaurus supports.

Commands​

Code blocks can include a single command or multiple commands. When introducing a code block, be sure to describe what the user will be doing.

note

When introducing a code block that involves executing a command, don't force the user to use a specific type of text editor, like vim or nano. Instead, use "in your preferred text editor" or similar wording.

Example - Single-command code block​

docker compose up -d mysql

Example - Multiple-command code block​

Then, clone the client SDK repository and download the tools and the generic contracts by running the following commands:

git clone https://github.com/scalar-labs/scalardl-java-client-sdk.git
cd scalardl-java-client-sdk
git checkout v$VERSION
curl -OL https://github.com/scalar-labs/scalardl-java-client-sdk/releases/download/v$VERSION/scalardl-java-client-sdk-$VERSION.zip
unzip scalardl-java-client-sdk-$VERSION.zip
mv scalardl-java-client-sdk-$VERSION client
curl -OL https://github.com/scalar-labs/scalardl/releases/download/v$VERSION/scalardl-generic-contracts-$VERSION.zip
unzip scalardl-generic-contracts-$VERSION.zip
mv scalardl-generic-contracts-$VERSION generic-contracts

Commands or code with placeholders​

If a code block includes placeholders that users need to replace before running the command(s), be sure to mention that in the instructions.

Example - One or two placeholders​

Create a scalardb-options.json file and add the following, replacing <HOSTNAME_OR_IP_ADDRESS> with the FQDN or the IP address, and <PORT> with the port number (60053 by default) of your cluster:

{
  "ScalarDbOptions": {
    "Address": "http://<HOSTNAME_OR_IP_ADDRESS>:<PORT>",
    "HopLimit": 10
  }
}

Example - Three or more placeholders​

To create namespaces and tables by using a properties file, run the following command, replacing the contents in the angle brackets as described:

java -jar scalardb-schema-loader-<VERSION>.jar --config <PATH_TO_SCALARDB_PROPERTIES_FILE> -f <PATH_TO_SCHEMA_FILE> [--coordinator]