Generate Ballerina By Examples

Overview

A script is used to take the source of the Ballerina By Examples (BBEs) from the ballerina-distribution repository as the input and generates the HTML files to be published on the Ballerina website.

Set up the prerequisites

1. Download and install Node.js.

2. Navigate to the directory, which includes the script.

   Note: The scripts can be found in the bbe-generation-v2 branch.

cd .github/scripts/bbe

3. Install the dependencies.

npm install

4. Navigate back to the root of the repo.

cd ../../..

Delete the existing BBE HTML files

You can do either of the below.

1. Delete all the HTML files located in the learn/by-examples directory excluding the 404.html and index.html files by executing the command below.

find learn/by-example -type f \( -name "*.html" ! -name "404.html" ! -name "index.html" \) -delete

2. Delete only the BBEs that you want to update from the learn/by-examples directory.

Run the script

The convertMarkdown.js script is used to convert the BBE content written in markdown to HTML.

Location from root of the website repo	.github/scripts/bbe/convertMarkdown.js
Inputs	1. Location of the examples directory. 2. Location of the output to be saved.
Outputs	HTML files corresponding to the markdown BBE files.

From the root of the ballerina-dev-website repository, run the script using Node.js.

node .github/scripts/bbe/convertMarkdown.js <relative_path_to_examples> <relative_path_for_output_HTMLs>

By default, the arguments of the above command will have the values below.

• <relative_path_to_examples> = “examples”
• <relative_path_for_output_HTMLs> = “learn/by-example”

An example command would be as follows.

node .github/scripts/bbe/convertMarkdown.js "../ballerina-distribution/examples" "learn/by-example"

Note: Generated output BBE HTML files will be saved in the specified directory.

Generate the BBE navigation content

Execute the command below to generate the YAML file with the BBE navigation content.

node .github/scripts/bbe/generateNav.js <relative_path_to_examples> <relative_path_to_data_directory>

An example command would be as follows.

node .github/scripts/bbe/generateNav.js "examples" "\_data"

Verify on the Ballerina website

Deploy the generated HTML files on the Ballerina website by replacing the <ballerina-dev-website>/learn/by-example directory and verify your changes locally.

Use the automated generation script

This script is used to automate the above manual process of generating the BBEs for the Next.js-based website. All the changes made in the BBEs would be saved locally in the swan-lake/by-example directory.

Note: This script clones the ballerina-distribution repository locally.

Before running the script, install the dependencies from the root of the project via the command below.

npm install

Execute the command below to run the generateBBEs.js script.

node .github/scripts/bbe/generateBBEs.js;