Improve Documentation

Since the engine is constantly evolving, you may notice some gaps in the documentation. You're going to know how to fix that!

The easy way

Requirements: you just need a Github account.

To update an existing page, just head to

This folder is the root of all static content used by the site itself.

Then pick a page you want to update and select the edit button:

quick edit

You can now use markdown to edit the documentation page.

Once done, try to quickly explain what your modification is for, and click on the Propose file change button:

propose file change

For now, your modification isn't yet in the main files. You have to ask to BabylonJS core team to validate and merge your work.

Press Create pull request button:

sending pull

If needed, modify your comment, and press again Create pull request button:

commenting pull

Congratulations, your modifications are now waiting to be validated and merged into the official documentation!

pull now waiting

Do not hesitate to read Good Practice section.

Deeper Changes

Sometimes, quick edits like above are not sufficient. Indeed, you might want to run the documentation locally on your computer before pushing online, just to be sure nothing is broken.



Start by going to the main BabylonJS Documentation repository and clicking on the Fork button:


This will make a copy of the repository, but on your account.

Click on Clone or download button, and Open in Desktop:

open locally

Github Desktop will be opened and ask you where you want to save your fork.

When the files are downloaded, open a command in this repo. It can be done quickly using Github Desktop menu:


(you may have Open in Command rather than Open in PowerShell , that's not a big deal)

You need 'npm', 'grunt' and 'grunt-cli' installed in the directory and you may need to update these from time to time.

Just write npm install, press enter and wait the operation to be done.

You may also need to install grunt globally. If so, use npm install -g grunt-cli.

This fork operation has to be done only once. You're now able to run locally the documentation by following the next section.

Running and editing the doc locally

We currently support Node 10 and down. Local build will fail with node 12 and up

In the powershell window at the root of the documentation repo, send a:

npm run build

command and wait. Should the build not occur try npm install, or updating npm, grunt, and grunt-cli.

When it's done, use:

npm run serve

This will launch the local documentation website on http://localhost:8080

Open the project using your favorite code editor. This can be done also from Github Desktop:

visual studio

(you may have Open in Atom rather than Open in Visual Studio , that's not a big deal)

You can finally starting to update the markdown files!

visual studio

Adding new images

In case you have to create new illustrations, you need to send them on the Github repo into a specific folder: Documentation/public/html/img/.

So on your local fork, go to this img folder. You can see there are already a lot of folders, so try to use existing folders to put your new images if possible.

Let says you just create a new page, linked on

Here, you can create a my_very_great_page folder into the /img/how_to/ one, and put my-wonderful-image.jpg into it.

Then, on your markdown page, use this link pattern:

![quick description (for accessibility)](/img/how_to/my_very_great_page/my-wonderful-image.jpg)

Of course, try to keep image size as low as you can (while keeping a good visual quality).

Adding new pages

Now that everything is working well, you may want to add new content. To do so, please open /data/statics.json.

This file is a catalog where you can reference new files added to the repo.

For example, let's say we want to add this page. We know that our new page will be in the Contribute section:

"How_To": [
    /* [...] */
        "title": "Contribute",
        "name": "contribute",
        "desc": "Suporting and Developing the Framework",
        "files": [
                "title": "Start Contributing to Babylon.js",
                "filename": "how_to_start"
                "title": "Follow Approved Naming Conventions",
                "filename": "Approved_Naming_Conventions"
            /* [...] */
    /* [...] */

Just add necessary information about your new page:

/* [...] */
    "title": "Start Contributing to Babylon.js",
    "filename": "how_to_start"
    "title": "Improve Documentation",
    "filename": "contribute_to_documentation"
    "title": "Follow Approved Naming Conventions",
    "filename": "Approved_Naming_Conventions"
/* [...] */

Notice the filename field. This will be your new page filename (without markdown extension .md):

new content

Sending pull request

A Pull Request (PR) has to be made to integrate your modifications into the documentation.

You will first pull your local modifications into your online fork, then ask for merging your fork into the main repo.

In Github Desktop, you will see all of your modifications. Sometimes a file named babylon.d.ts will automatically be modified, but there's no problem to PR with it.

Add an explicit summary into the required field, and click to Commit to master:


Then, click on Push origin button:


And go to your online github repo. You can use Github Desktop for that:


For now, your fork is updated online, having your last modifications.

Click on New pull request button:

github pull

If no conflicts, you will be able to follow the same steps as we seen above in the easy way section.

Congratulation again, you're now a documentation master!

Good Practices


  • if you're not familiar with markdown, you can read this short Github guide
  • even if you're seeing just a tiny typo, feel free to do a pull request dedicated to it
  • do one commit per tasks, a pull request can take into account multiple commits if needed
    • example: if you have two pages to modify, once the first page is edited, do a commit
  • tables can be a great help for readability
  • avoid the use of first person
  • pay attention to spelling, grammar and punctuation
  • when you're not sure about a point, ask for proof-reading


  • use and store images from the documentation FTP as much as possible, read Adding new images
  • be careful about image size (tip: Photoshop has a "Save for the web" export)


  • when showing a JavaScript block of code, inform Markdown that it's JavaScript to ensure syntax highlighting:

markdown code

  • when quoting a property in a sentence, you can use single _`_ char (Alt + numpad 96)
    • example: You can set the roughness of a PBR material to 1.


  • use lowercases on your url
    • example: /how_to/ in place of /How_To/
  • use relative links
    • example: [Load Files with Assets Manager](/how_to/how_to_use_assetsmanager) instead of [Load Files with Assets Manager](

Further Reading

  • try to always add a Further Reading section
  • sort Further Reading using main documentation sections (Babylon 101, How to, etc)
  • use markdown list
  • do not hesitate to link API relative to the article


# Further Reading

## Babylon 101

- [How to get Babylon.js](/babylon101/how_to_get)

## How To

- [Use the glTF File Loader Plugin](/how_to/gltf)
- [Use the OBJ File Loader Plugin](/how_to/obj)
- [Use the STL File Loader Plugin](/how_to/stl)
- [Load Files with Assets Manager](/how_to/how_to_use_assetsmanager)

## Resources

- [Available Meshes for Importing into Playground](/resources/meshes_to_load)
- [Using External Assets in the Playground](/resources/external_pg_assets)

## API

- [SceneLoader](/api/classes/babylon.sceneloader.html)

Further Reading

How To