Documentation for Cocos2d-x, Cocos2d-html5, Cocos Creator, Programmers Guide, Installation
JavaScript C++ CSS HTML Objective-C++ Shell Other
Latest commit 7360d31 Jan 13, 2017 @slackmoehrle slackmoehrle committed on GitHub Merge pull request #920 from dimidrola/patch-1
wrong variable misleading


This is the Cocos Documentation Repo. It is licensed under the Creative Commons BY-SA license.

You can read these docs online.

This repo builds

  • Cocos docs
  • Installation docs
  • Programmers Guide
  • API-Reference
  • Services, like SDKBOX

Directory layout

  • api-ref/ - API Reference, does a lot here that is not in this dir.
  • - a blank page that is used when building print versions
  • - BASH script that build web and print versions, deploys to staging server
  • catalog/ -
  • cocos/ - docs relating to Cocos
  • - this script deploys the docs to
  • - this is the main landing page, part static, part dynamically created in
  • installation/ - docs relating to installation on supported platforms
  • - licensing
  • manual/ -
  • mkdocs.yml - MKDocs configuration
  • programmers-guide/ - The Cocos2d-x Programmers Guide
  • - this file :-)
  • release-notes/ - release notes
  • services/ - docs relating to supported services, like SDKBOX
  • static-pages/ - static pages that we need
  • styling/ - CSS for print version of the Programmers Guide
  • theme/ - custom theme for web version
  • - title page
  • tutorial/ - Tutorials

What do you need to build for OS X?

How to run/test these docs

  • cd <where you cloned this repo>
  • run --all
  • run mkdocs serve

Any changes made while mkdocs serve is running are automatically rebuilt.

How to build for deployment

  • cd <where you cloned this repo>
  • run --all

Content is built in docs and deployed to site. This script also builds the ePub and PDF versions as well as deploys out to our staging server and


The legacy API-Refs are now downloaded and deployed as needed. No need for us to store these in GitHub as they don't change.

  • cd <where you cloned this repo>
  • run --legacyapi

When contributing

  • make sure to break lines at 80 columns.
  • edit via a pull request. Please do not edit chapters and push directly.
  • if you are creating a new document, please don't make it feel and sound like an API Reference. Please tell a story about your content. We want to make this engage the user. If in doubt: read Chapter 2 and notice it feels like a chapter in a book.
  • contact me via e-mail or on the forums to discuss what you want to add, edit, etc.

Additional layout notes

  • each chapter has a markdown file and 3 image directories associated with it.
  • the image directories are -web, -print and -img. -web is properly sized images for displaying on the web. print is properly sized images for displaying in the epub and pdf. -img is were to put the original images (also displayed when viewing from GitHub).
  • the script does copying and renaming of directories during the build process since the markdown files expects files at a specific path. Take a look.
  • if a chapter does not have any images there is no need to create directories for it.

Supporting multiple languages (cpp, js, lua)

To support C++, JavaScript, (and technically Lua when ready), you can easily embed div elements and put the content for that language in between:

Example for C++:

  <div class="langs">
    <li><a href="#" id="tab-cpp">C++</a></li>
    <li><a href="#" id="tab-js">Javascript</a></li>
  <div class="tab-cpp tab_content">

some content that is c++ specific.....

more c++ specific content....
auto mySprite = Sprite::create("mysprite.png");
even more c++ specific content....

Example for Javascript:

  <div class="tab-js tab_content">

some javascript specific content...
var mySprite = Sprite.create("mysprite.png");
more javascript content....


Note: there is a blank line after the opening div and before the closing div elements. This is a markdown requirement or else it will not render properly.

Note: Also notice that the div elements are indented by a single tab. This is also a markdown requirement or else the text will not render properly.

If you find an error