This repository contains the source code of the Bold BI documentation.
- Prerequisites
- Setup the Application for Local Environment
- CI Validations
- File Structure
- Important Markdown Guidelines
- General Markdown Syntax Reference
Bold BI documentation was built on Gatsby application.
Make sure to install Node.js v18
series(This version of nodejs
supports all the Gatsby
plugin which is used in our application, higher version may not be supported all the plugins.) in your machine and run node -v
to check whether it is installed properly or not.
Install gulp
package with global access and the version should be v4.0.2
and then run gulp -v
to check whether it is installed properly or not.
To Run:
npm install gulp@4.0.2 -g
Download and install python
package.
Install gatsby-cli
package with global access to build and serve the application.
To Run:
npm install gatsby-cli@5.11.0 -g
Initially, Run npm install
from your cloned root folder.
To Run:
npm install
Run the below command to build the application.
To Run:
gulp build
Run the below command to serve the application. After running the command, Navigate to localhost:8000 to view the documentation in local browser.
To Run:
gulp serve
Once we done the setup for local environment, we can follow the below commands to check the validations. Also, explained the solutions for the commonly raised validation errors.
- Run the below command to test typo error.
To Run:
gulp typo
Note: This task will throw an error on using custom words like dll, localhost
. For that, we need to include these words (need to have valid reason for using these custom names) in spelling
file.
- Run the below command to test file name validation.
To Run:
gulp file-validation
Note: This task will throw error on using custom file names. For that, we need to include these names(need to have valid reason for using these custom names) in customNames
array in config.json
file.
- Run the below command to test seo validation.
To Run:
gulp seo-validation
- Run the below command to test all the typo error, seo validation and file name validation.
To Run:
gulp test
Documents should have written in markdown(.md)
format.
Refer the below document folder structure,
--> docs (1)
--> getting-started
--> quick-start.md
--> index.md
--> index.md (4)
--> summary.json (5)
--> home.md (6)
(1) ---> Document .md
files should be placed in docs folder.
(2) ---> Each parent folder should have index.md
file that explains about the overview of child nodes.
(3) ---> summary.json
file holds the title of each files presents in the parent folder. This will helps to show the titles in left pane of the documentation site. So, add the titles here with respect to each platform.
Image should be placed in this location \static\assets\
. Same document folder structure should be followed here.
Image name and Alt text should be unique and meaningful.
Swagger files should be placed in api folder and its respective index files should be placed in respective platform folders. Refer the rest-api-reference folder in \api\server-api-reference\
.
- All files should have
.md
extension. - Phrase title and description in a way that users can determine what questions the text will answer, and material that will be addressed, without reading the content. This eases the time spent looking for answers, and improvises search/scanning, and possibly SEO.
For example, at the top section of each MD file,
title: Dashboard Migration Utility - Embedded | Bold BI Learning
description: Learn how to migrate the classic platform dashboards and data sources into Bold BI Embedded supported formats using migration utility.
- For duplicated files, we should add
canonical
path (original file path).
For example, Migration Utility
support presents in both Cloud and Embedded BI Platform. So we need to add the migration-utility
file in both platform folders(\docs\cloud-bi\migration-utility & \docs\embedded-bi\migration-utility). In this file, same details will be given. So need to add original file path in canonical tag like below in duplicated file.
canonical: "/migration-utility/"
To add the notes and important type of predefined blockquote use the below syntax,
Syntax : > **NOTE:** [Content]
and > **IMPORTANT:** [Content]
- Refer General Markdown Syntax here.