
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](https://github.com) account.

To update an existing page, just head to https://github.com/BabylonJS/Documentation/tree/master/content

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](/img/contribute/documentation/easy-edit.png)

You can now [use markdown](https://guides.github.com/features/mastering-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](/img/contribute/documentation/easy-submit.png)

For now, your modification isn't yet in the main files. You have to ask toBabylon.js core team to validate and merge your work.

Press _Create pull request_ button:

![sending pull](/img/contribute/documentation/easy-pull.png)

If needed, modify your comment, and press again _Create pull request_ button:

![commenting pull](/img/contribute/documentation/easy-pull2.png)

Congratulations, your modifications are now waiting to be validated and merged into the official documentation!

![pull now waiting](/img/contribute/documentation/easy-pull-waiting.png)

Do not hesitate to read the [Good Practice](/contribute/contributeToDocs#good-practices) section.

## Deeper Changes

Sometimes, quick edits like described 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.

Requirements:

- a [Github](https://github.com) account
- [git](https://www.git-scm.com/downloads)
- [Github Desktop](https://desktop.github.com/) (optional, but makes local git repositories easier to use)
- [node.js](https://nodejs.org/en/), we support node 12 and up.
- [yarn](https://yarnpkg.com/getting-started/install)

### Forking

Start by going to the main Babylon.js [Documentation](https://github.com/BabylonJS/Documentation) repository and clicking on the _Fork_ button:

![fork](/img/contribute/documentation/further-fork-creation.png)

This will make a copy of the repository, but on your account.

Click on the _Clone or download_ button, and _Open in Desktop_:

![open locally](/img/contribute/documentation/further-open-desktop.png)

Github Desktop will be opened and ask you where you want to save your fork.

When the files are downloaded, open a terminal/command prompt in this repo. It can be done quickly using the Github Desktop menu:

![powershell](/img/contribute/documentation/further-powershell.png)

(_you may have_ Open in Command _rather than_ Open in PowerShell _, that's not a big deal_)

You need 'yarn' installed. For further information about yarn, you can go to the [yarn installation guide](https://yarnpkg.com/getting-started/install).

After installing yarn, type `yarn install`, press <kbd>enter</kbd>, and wait for the operation to finish.

This fork operation only has to be done once. You're now able to run locally the documentation by following the next section.

### Running and editing the doc locally

Run:

`yarn run dev`

This will launch the dev server on http://localhost:3000

Open the project using your favorite code editor. This can be done also from Github Desktop:

![visual studio](/img/contribute/documentation/further-visual-studio.png)

(_you may have_ Open in Atom _rather than_ Open in Visual Studio _, that's not a big deal_)

You can finally start to update the markdown files!

![visual studio](/img/contribute/documentation/further-editing.png)

### 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/img/`](https://github.com/BabylonJS/Documentation/tree/master/public/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 `https://doc.babylonjs.com/divingDeeper/my_very_great_page`.

Here, you can create a `my_very_great_page` folder into the `/img/divingDeeper/` one, and put `my-wonderful-image.jpg` into it.

Then, on your markdown page, use this link pattern:

```markdown
![quick description (for accessibility)](/img/divingDeeper/my_very_great_page/my-wonderful-image.jpg)
```

Of course, try to keep the image size as small as you can (while keeping a good visual quality). Our build system will do its best to optimize the image nonetheless.

### Adding new pages

#### Page structure

Now that everything is working well, you may want to add new content. To do so, please open `/configuration/structure.json`.

This file is a catalog where you can reference new files added to the repo.

The file is a tree of documents, starting from the root page and going to the different sections. Each page can (but not must) have its own children.

For example, let's say we want to add this page. We know that our new page will be in the _Diving Deeper/Audio_ section:

```javascript
{
    "friendlyName": "Home Page",
    "content": "landing_pages/home",
    "children": {
    /* [...] */
    "divingDeeper": {
            "friendlyName": "Diving Deeper",
            "children": {
              /* [...] */
              "audio": {
                    "friendlyName": "Audio",
                    "children": {
                        "playingSoundsMusic": { "friendlyName": "Playing Sounds and Music", "children": {}, "content": "How_To/audio/Playing_sounds_and_music" },
                        // This is the place you will add your document
                    },
                    "content": "landing_pages/divingDeeperAudioLandingPage"
                },
            }
    }
    /* [...] */
}
```

Just add necessary information about your new page:

```javascript
/* [...] */
"documentKeyAndUrl": {
  "friendlyName": "A friendly title to your document",
  "children": {/* if any, children will contain the rest of the documents */},
  "content": "the markdown file that correlates to this document."
},
/* [...] */
```

Notice the object's key. This will be your new page filename (without markdown extension .md):

![new content](/img/contribute/documentation/further-new-content.png)

#### Page metadata

Each page can (but not must) have a metadata section, that provides further information for this page. This is important if you want the page to be visible when being searched.

The metadata section is a YAML, added to the top of the page:

```yaml
---
title: Page title, if you want to override the title from the structure file
image: A link to an image that will be used as this page's image
description: A short description for this page
keywords: comma-separated keywords for this page.
further-reading: A list of links to add at the end of this page. Can be internal or external links
video-overview: A youtube video id to show at the beginning of this page
video-content: a list of videos (youtube or files) to show at the end of the page.
---
```

For example, this is a part of the metadata in the node_material page:

```yaml
---
title: Node Material
image: /img/pageImages/nodeMaterial.jpg
description: The Node Material is a simple, highly customizable material that you can build yourself piece by piece. Combined with the powerful node-based editor, you can easily create stunning custom GPU shaders and FX for your Babylon.js scenes.
keywords: shaders, glsl, node editor, graphics, GPU program, material, NME, Node Material, Node Material Editor
further-reading:
  - title: Dedicated NME Forum Examples
    url: https://forum.babylonjs.com/t/node-materials-examples/6048
  - title: 3 Tips For Getting Started Building Procedural Node Material Shaders
    url: https://babylonjs.medium.com/procedural-node-material-shaders-3-tips-for-getting-started-4089c1832dfc
  - title: Mesh shattering with baked physics
    url: https://babylonjs.medium.com/mesh-shattering-with-baked-physics-5b3f8f381743
  - title: Fighting Self-Doubt, with Water
video-content:
  - title: Node-Based Procedural Textures
    url: https://youtu.be/qqMuuSM7GvI
  - title: Creating Procedural Node Materials Through Code
    url: https://youtu.be/GrmVObi6caQ
  - title: Node Material Post Processes
    url: https://youtu.be/QTuL5raapQQ
  - title: Node Material Editor Particles!!!!
    url: https://youtu.be/fZvZMXDoVp4
  - title: Interactive Hex Tile Series
    url: https://www.youtube.com/playlist?list=PLsaE__vWcRamMC5oJwhrSj3x3jT9TWOPB
  - title: Unraveling Advanced Anisotropic Reflections
---
```

Everything in the metadata is optional and has a different value. However, it is always better to add as much information as possible. This will help people find and use the page. And this is the goal here!

The image provided will be used when sharing this link on sites supporting open graph, such as Facebook, Medium, Twitter, and so on. The default image is the Babylon.js logo.

#### Internal links

To link to an internal document, use its path from the root without adding the domain. For example:

```markdown
[Post Processes](/features/featuresDeepDive/postProcesses/usePostProcesses)
```

### Adding examples

It is always great to provide examples in your documentation page. By using the correct markdown, you can add playgrounds and NME, and they will be added automatically to the page's side menu.

To add a playground, add the following code:

```html
<Playground id="playgroundId" title="Playground title" description="A short description" image="Optional image url" />
```

The playground ID is the 6-character id, and the version number if needed. For example: `#Y642I8#2`.

The same applies to NME examples:

```html
<NME id="nmeId" title="NME title" description="A short description" />
```

This can be either inline or in a new line and will automatically add the external and example link.

An image will be generated for each playground without an image, so don't worry about screen-capturing your playground. Please commit those images along with your document!

### Adding media (videos and images)

To add a youtube link, use the youtube markdown tag:

```html
<Youtube id="qqMuuSM7GvI" />
```

To add an image, you can use the markdown annotation:

```markdown
![Particle choice](/img/how_to/Materials/particleMenu.png)
```

but you can also use the more advanced `<img/>` tag, that has more control over formatting, size and so on. As always, everything is optional, but very nice to have:

```html
<img src="internal link to image" title="Image title" alt="Similar to title" width="300" height="200" caption="Copyright (or any other) caption that will appear under the image" />
```

### 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_:

![pushing](/img/contribute/documentation/further-pushing.png)

Then, click the _Push origin_ button:

![push](/img/contribute/documentation/further-push.png)

And go to your online Github repo. You can use Github Desktop for that:

![github](/img/contribute/documentation/further-github.png)

For now, your fork is updated online, having your last modifications.

Click the _New pull request_ button:

![github pull](/img/contribute/documentation/further-github-pull.png)

If no conflicts, you will be able to follow the same steps as we seen above in the [easy way](/contribute/contributeToDocs#the-easy-way) section.

Congratulation again, you're now a documentation master!

## Good Practices

### General

- if you're not familiar with markdown, you can read this short [Github guide](https://guides.github.com/features/mastering-markdown/)
- 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

### Images

- use and store images from the documentation FTP as much as possible, read [Adding new images](/contribute/contributeToDocs#adding-new-images)
- be careful about image size (tip: Photoshop has a "Save for the web" export)

### Code

- when showing a block of JavaScript or TypeScript, include the language name after the code block starting ticks to ensure syntax highlighting:

![markdown code](/img/contribute/documentation/markdown-code.png)

- when quoting a property in a sentence, you can use single _\`_ char (<kbd>Alt</kbd> + numpad <kbd>96</kbd>)
  - example: You can set the `roughness` of a PBR material to 1.

### Links

For links to other parts of the Babylon.js documentation and API, use relative links.

For example, use `[Load Files with Assets Manager](/contribute/contributeToDocs)` rather than `[Load Files with Assets Manager](https://doc.babylonjs.com/divingDeeper/developWithBjs/contributeToDocs)`

## Further Reading

Any articles, URLs, documents, and links that you'd like the reader to have as a reference on the page should go into the "further reading" metadata section at the top of the page. See [Page Metadata](#page-metadata) for more detail.



## Introduction

Babylon.js is maintained on Github, a web-based hosting service for version control using Git. Familiarity with using Github is necessary for you to contribute.

## Pre-Requisites

- Installation of Node.js, NPM, Git, Typescript, Gulp and have a Github Account;
- A fork and clone of Babylon.js;
- Reading the [contribution guidelines](https://github.com/BabylonJS/Babylon.js/blob/master/contributing.md);
- An IDE such as VSCode;
- An ability to code in Typescript. Babylon.js is written in Typescript then compiled and distributed in JavaScript.

At the time of writing the version of Gulp needed was 4.0.0. The current [What's New](//doc.babylonjs.com/whats-new) should indicate if there have been any changes of version. You can also look in the Babylon.js repository for `package.json` in `Tools/Publisher` which will give the version number for Gulp and Typescript.


## Contributions

You can contribute to either the Babylon.js engine directly or the documentation for it. The documentation is split into two parts, the 'tutorial' section and the API. The documentation for the API is written from comments within the code for Babylon.js so that details of how to contribute to the API fall under this section.


Babylon.js can be used to build experiences on many different platforms for
all kinds of devices, and even provides
[ways to target multiple platforms simultaneously](/setup/templates/repos/templateRepositories#the-template-repository-workflow)!
So, what are you making?

## Web App

The Web is Babylon's native habitat, and Babylon.js can be integrated into
just about any Web development workflow. Here are just a few of the
available recommended ways to build a Web app with Babylon.js.

- You could use the
  [Template Repository Workflow](/setup/templates/repos/templateRepositories#the-template-repository-workflow)
  to develop your Babylon.js experience as a portable NPM package which
  could then be incorporated into all sorts of other projects.
- You could build a single-repo project focused specifically on
  Babylon.js, as exemplified by
  [this repo](https://github.com/RaananW/babylonjs-webpack-es6).
- You could package and deploy your Web app using
  [Ionic](https://ionicframework.com/), which will also allow you to
  target PWA and mobile app platforms. The
  [_Fruit Fallin'_ Dev Story](/guidedLearning/devStories/fruitFalling)
  illustrates a way to do this using the Template Repository Workflow.
- You could incorporate your experience into a larger pre-existing Web app
  built with technologies like
  [WordPress](https://wordpress.com/)
  and
  [React.js](https://reactjs.org/).
  The
  ["Vaporwear" Custom Experience Dev Story](/guidedLearning/devStories/vaporwearConfigurator)
  illustrates a way to do this using the Template Repository Workflow.

...just to name a few. If you'd like to discuss or have questions about a
particular option, we'd love to hear from you on
[the forum](https://forum.babylonjs.com/c/questions/)!

## Mobile App

There are several excellent ways to ship your Babylon.js experience in a
mobile app for Android or iOS. The following are a few of the best:

- [Ionic](https://ionicframework.com/), as mentioned above, is a great
  choice for targeting Web, PWA, and mobile platforms at the same time.
  The
  [_Fruit Fallin'_ Dev Story](/guidedLearning/devStories/fruitFalling)
  illustrates a way to do this using the
  [Template Repository Workflow](/setup/templates/repos/templateRepositories#the-template-repository-workflow).
- For
  [React Native](https://reactnative.dev/)
  developers,
  [Babylon React Native](https://github.com/BabylonJS/BabylonReactNative)
  is specifically designed to make it as simple as possible to
  incorporate Babylon.js functionality directly into your React Native
  app. It's also possible to embed Web-targeting code into a WebView
  inside a React Native app.
- For developers who really need to get down to the metal,
  [Babylon Native](https://github.com/BabylonJS/BabylonNative) supports
  mobile platforms and allows the use of Babylon.js inside your entirely
  custom native applications, allowing for complete control of the
  app's entire technology stack.

If you're considering Babylon Native or Babylon React Native, you might
be interested in
[Babylon Native's own more detailed documentation](https://github.com/BabylonJS/BabylonNative/blob/master/Documentation/WhenToUseBabylonNative.md);
and, of course, any and all questions are welcome on
[the forum](https://forum.babylonjs.com/c/questions/).

## Desktop App

- Though it doesn't provide a native target for desktops,
  [Ionic](https://ionicframework.com/)
  still allows for the creation of apps "installable" on desktops in the
  form of PWAs, making this an excellent choice if you want to target
  everything at once. The
  [_Fruit Fallin'_ Dev Story](/guidedLearning/devStories/fruitFalling)
  illustrates a way to do this using the
  [Template Repository Workflow](/setup/templates/repos/templateRepositories#the-template-repository-workflow).
- [Electron](https://www.electronjs.org/)
  is a great option for natively targeting desktop platforms in a similar
  way to how Ionic and React Native are great options for mobile
  platforms. Since Electron uses NPM, it also works well with the
  Template Repository Workflow.
- Developers who need full platform access or are trying to integrate
  Babylon.js into existing native applications may be best served by
  [Babylon Native](https://github.com/BabylonJS/BabylonNative),
  which supports all major desktop platforms and gives the developer
  complete control of the technology stack.

As mentioned above, you might be interested in
[Babylon Native's own more detailed documentation](https://github.com/BabylonJS/BabylonNative/blob/master/Documentation/WhenToUseBabylonNative.md)
if you're considering either Babylon Native or Babylon React Native;
and, as always, please don't hesitate to bring any questions you have to
[the forum](https://forum.babylonjs.com/c/questions/).

## ... and More

Of course, this list isn't comprehensive and these aren't the only kinds
of apps: there are
[VR apps](/features/featuresDeepDive/webXR),
[server-side apps](/setup/support/serverSide),
[multi-device apps](/guidedLearning/networking/Colyseus),
and so many more possibilities that we could never hope to enumerate
them. Cross-platform support is a key objective for Babylon; so
no matter which or how many platforms your app needs to run on, we'd love
to hear about it and help make sure Babylon provides the tools you need
to succeed. Thanks for considering Babylon.js!


Contribute

Contributions

Coming next

Contributing to Babylon.js

Learn how to start contributing to Babylon.js.

Contribute To The Documentation

Learn how to contribute to the Babylon.js Documentation.