How To

Improve Documentation


Since the engine is constantly evolving, you may notice some lacks 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 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

You can now use markdown to edit the documentation page.

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

propose file change

For now, your modification aren'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

Going further

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

Requirements:

Forking

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

fork

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:

powershell

(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

In the powershell window at the root of the documentation repo, send a grunt build command and wait. Should the build not occur try updating 'npm', 'grunt, and 'grunt-cli'.

When it's done, use grunt 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 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 informations 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

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 your modifications.

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

pushing

Then, click on Push origin button:

push

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

github

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!