Create Ballerina By Examples

Overview

This document demonstrates how to add a BBE and write its content using markdown syntax.

Info: For best practices to be followed when creating BBEs, see Ballerina By Example guidelines.

Select the branch to send the BBE update

The BBE sources can be found in the <ballerina-distribution-repo>/examples/ directory. You can select the branch to update the BBEs as follows.

• master branch - BBE updates that should immediately be reflected in the live site
• respective update release branch (e.g., release-2201.2.0) - BBE updates of the next update release
• 2201.0.x branch - BBE updates of the next patch release

Create the directory structure of a BBE

Below is the directory structure of a BBE directory (in the ballerina-distribution repo).

Info: In addition to this basic structure, you can add .proto,.conf, and .toml etc. files also to be displayed on the website. For example, see the GRPC bidirectional streaming BBE.

• .bal - sample code to display on the Ballerina website.
• .md - sample content displayed in each example on the Ballerina website. The name should be the same as the name of the directory with hyphens replaced by underscores.
• .out - output of the sample displayed at the bottom inside a black colour box on the Ballerina website. The output file for a particular .bal file should have the same name as the .bal file but with the .out extension.
• _test.bal - Contains the test to validate the output of the BBE during the build time.
• .metatags - Contains the meta description and keywords to build SEO in the webpage. The description should be 50-160 characters long, and there should be 3-5 keywords that are comma-separated. For example, see the hello_world.metatags file.

Create the markdown file

In the BBE folder (./examples/<bbe-url>), if a markdown file doesn’t exist, create a new markdown file with the name of the BBE.

E.g., hello_world.md

Write the BBE body content

• The content written in the markdown file will be rendered in the body of the BBE page. The page content will be created in the order the content is written in the markdown file.

• The content can include any markdown syntax. In the converting process, they will be converted into corresponding HTML tags.

• Apart from the basic markdown syntax, there are 2 special syntax for ballerina code snippets and ballerina outputs of a BBE.

Component	Syntax
Ballerina Code	::: code <resource_file_name> :::
Output	::: out <resource_file_name> :::

E.g.,

1. ::: code hello_world.bal :::
2. ::: out hello_world.out :::

Generate the HTML BBE pages from the markdown files

The convertMarkdown.js script located at <ballerina-dev-website-repo>/.github/scripts/bbe is used to generate the HTML BBE pages using the markdown files.

Info: For more details on the markdown converter script, see Generate Ballerina By Examples.