Migrating all the map-building documentation to Github.

+ adding links to Youtube tutorials

docs/maps/entry-exit.md

@@ -0,0 +1,67 @@
+{.section-title.accent.text-primary}
+# Entries and exits
+
+https://www.youtube.com/watch?v=MuhVgu8H7U0
+
+## Defining a default entry point
+
+In order to define a default start position, you MUST create a layer named "`start`" on your map. This layer MUST contain at least one tile. The players will start on the tile of this layer. If the layer contains many tiles, the players will start randomly on one of those tiles.
+
+![Start layer screenshot](images/start_layer.png)
+
+In the screenshot above, the start layer is made of the 2 white tiles. These tiles are not visible to the end user because they are hidden below the "bottom" layer that displays the floor of the map.
+
+{.alert.alert-info}
+**Pro tip**: if you expect many people to connect to your map at the same time (for instance, if you are organizing a big event), consider making a large start zone. This way, users will not all appear at the same position and will not pop randomly in a chat with someone connecting at the same moment.
+
+## Defining exits
+
+In order to place an exit on your scene that leads to another scene:
+
+*   You must create a specific layer. When a character reaches ANY tile of that layer, it will exit the scene.
+*   In layer properties, you MUST add "`exitUrl`" property. It represents the URL of the next scene. You can put relative or absolute URLs.
+*   If you want to have multiple exits, you can create many layers. Each layer has a different key `exitUrl` and has tiles that represent exits to another scene.
+
+![](images/exit_layer_map.png)
+
+{.alert.alert-warning}
+**Note:** in older releases of WorkAdventure, you could link to a map file directly using properties `exitSceneUrl` and `exitInstance`. Those properties are now **deprecated**. Use "`exitUrl`" instead.
+
+## Understanding map URLs in WorkAdventure
+
+There are 2 kinds of URLs in WorkAdventure:
+
+*   Public URLs are in the form `https://play.workadventu.re/_/[instance]/[server]/[path to map]`
+*   Private URLs (used in paid accounts) are in the form `https://play.workadventu.re/@/[organization]/[world]/[map]`
+
+Assuming your JSON map is hosted at "`https://example.com/my/map.json`", then you can browse your map at "`https://play.workadventu.re/_/global/example.com/my/map.json`". Here, "global" is a name of an "instance" of your map. You can put anything instead of "global" here. People on the same instance of the map can see each others. If 2 users use 2 different instances, they are on the same map, but in 2 parallel universes. They cannot see each other.
+
+## Defining several entry points
+
+Often your map will have several exits, and therefore, several entry points. For instance, if there is an exit by a door that leads to the garden map, when you come back from the garden you expect to come back by the same door. Therefore, a map can have several entry points. Those entry points are "named" (they have a name).
+
+In order to create a named entry point:
+
+You can create a new layer for your entry point or use an existing layer with named tiles.
+
+*   If you don't use the layer named "`start`", you MUST add a boolean "`startLayer`" property to the layer properties. It MUST be set to true.
+*   If you use this method, when a character enters the map by this entry point, it will enter randomly on ANY tile of that layer. The name of the entry point is the name of that layer.
+
+![](images/layer-entry-point.png)
+
+You can also use the tiles properties to create entry point.
+
+*   To do that, you will need to have a layer named "`start`" or with the "`startLayer`" property. Then you MUST add a string "`start`" property to a tile than you use in that layer. The name of the entry point is the value that property.
+*   If you use this method, when a character enters the map by this entry point, it will enter on ANY tile of the same kind in that layer.
+
+![](images/tile-entry-point.png)
+
+Notes :
+
+*   Two tiles with a string "start" property with different value can be in the same layer of entries.
+*   A tile with a string "start" property that is not in a layer of entries won't usable as an entry point.
+
+How to use entry point :
+
+*   To enter via this entry point, simply add a hash with the entry point name to the URL ("#[_entryPointName_]"). For instance: "`https://workadventu.re/_/global/mymap.com/path/map.json#my-entry-point`".
+*   You can of course use the "#" notation in an exit scene URL (so an exit scene URL will point to a given entry scene URL)

docs/maps/hosting.md

@@ -0,0 +1,25 @@
+{.section-title.accent.text-primary}
+# Hosting your map
+
+The [Getting Started](.) page proposes to use a "starter kit" that is relying on GitHub pages for hosting the map. This is a fairly good solution as GitHub pages offers a free and performant hosting.
+
+But using GitHub pages is not necessary. You can host your maps on any webserver.
+
+{.alert.alert-warning}
+If you decide to host your maps on your own webserver, you must **configure CORS headers** in your browser to allow access from WorkAdventure.
+
+## Configuring CORS headers
+
+CORS headers ([Cross Origin Resource Sharing](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)) are useful when a website want to make some resources accessible to another website. This is exactly what we want to do. We want the map you are designing to be accessible from the WorkAdventure domain (`play.workadventu.re`).
+
+### Enabling CORS for Apache
+
+In order to enable CORS in your Apache configuration, you will need to ensure the `headers` module is enabled.
+
+In your Apache configuration file, simply add the following line inside either the `<Directory>`, `<Location>`, `<Files>` or `<VirtualHost>` sections, or within a `.htaccess` file.
+
+    Header set Access-Control-Allow-Origin "*"
+
+### Enabling CORS on another webserver
+
+Check out [enable-cors.org](https://enable-cors.org/server.html) which has detailed instructions on how to enable CORS on many different webservers.

docs/maps/index.md

@@ -0,0 +1,128 @@
+{.section-title.accent.text-primary}
+# Create your map
+
+## Tools you will need
+
+In order to build your own map for WorkAdventure, you need:
+
+*   the [Tiled editor](https://www.mapeditor.org/) software
+*   "tiles" (i.e. images) to create your map
+*   a web-server to serve your map
+
+WorkAdventure comes with a "map starter kit" that we recommend using to start designing your map quickly. It contains **a good default tileset** for building an office and it proposes to **use Github static pages as a web-server** which is both free and performant. It also comes with a local webserver for testing purpose and with Typescript support (if you are looking to use the [map scripting API]({{url('/map-building/scripting')}}).
+
+{.alert.alert-info}
+If you are looking to host your maps on your own webserver, be sure to read the [Self-hosting your map](hosting.md) guide.
+
+[](https://www.youtube.com/watch?v=lu1IZgBJJD4)
+
+## Getting started
+
+Start by [creating a GitHub account](https://github.com/join) if you don't already have one.
+
+Then, go to the [Github map starter kit repository page](https://github.com/thecodingmachine/workadventure-map-starter-kit) and click the **"Use this template"** button.
+
+<figure class="figure my-5">
+    <img src="images/use_this_template.png" class="figure-img img-fluid rounded" alt="" style="width: 70%" />
+    <figcaption class="figure-caption">The "Use this template" button</figcaption>
+</figure>
+
+You will be prompted to enter a repository name for your map.
+
+<figure class="figure my-5">
+    <img src="images/create_repo.png" class="figure-img img-fluid rounded" alt="" style="width: 70%" />
+    <figcaption class="figure-caption">The "create a new repository" page</figcaption>
+</figure>
+
+**Make sure to check the "Include all branches" checkbox, otherwise the Github Pages deployment process will not be setup automatically.**
+
+If you miss that step, don't worry, you can always fix that by clicking on the **Settings tab** of your repository and scroll down to the **GitHub Pages** section. Then select the **gh-pages** branch. It might already be selected, but please be sure to click on it nonetheless (otherwise GitHub will not enable GitHub pages).
+
+{.alert.alert-info}
+If you only see a "master" branch and if the **gh-pages** branch does not appear here, simply wait a few minutes and refresh your page. When you created the project, Github Actions triggered a job that is in charge of creating the **gh-pages** branch. Maybe the job is not finished yet.
+
+<figure class="figure my-5">
+    <img src="images/github_pages.png" class="figure-img img-fluid rounded" alt="" style="width: 70%" />
+    <figcaption class="figure-caption">The GitHub pages configuration section</figcaption>
+</figure>
+
+Wait a few minutes... Github will deploy a new website with the content of the repository. The address of the website is visible in the "GitHub Pages" section.
+
+<figure class="figure my-5">
+    <img src="images/website_address.png" class="figure-img img-fluid rounded" alt="" style="width: 70%" />
+    <figcaption class="figure-caption">Your website is ready!</figcaption>
+</figure>
+
+Click on the link. You should be redirected directly to WorkAdventure, on your map!
+
+## Customizing your map
+
+Your map is now up and online, but this is still the demo map from the starter kit. You need to customize it.
+
+### Cloning the map
+
+Start by cloning the map. If you are used to Git and GitHub, simply clone the map to your computer using your preferred tool and [jump to the next chapter](#loading-the-map-in-tiled).
+
+If you are new to Git, cloning the map means downloading the map to your computer. To do this, you will need Git, or a Git compatible tool. Our advice is to use [GitHub Desktop](https://desktop.github.com/). We recommend you take some time mastering the notion of pull / commit / push as this will make uploading your maps really easier.
+
+As an (easier) alternative, you can simply use the "Export" button to download the code of the map in a big Zip file. When you want to upload your work again, you will simply drag'n'drop your files in the GitHub website.
+
+### Loading the map in Tiled
+
+The sample map is in the file `map.json`. You can load this file in [Tiled](https://www.mapeditor.org/).
+
+Now, it's up to you to edit the map and write your own map.
+
+Some resources regarding Tiled:
+
+*   [Tiled documentation](https://doc.mapeditor.org/en/stable/manual/introduction/)
+*   [Tiled video tutorials](https://www.gamefromscratch.com/post/2015/10/14/Tiled-Map-Editor-Tutorial-Series.aspx)
+
+### Testing your map locally
+
+In order to test your map, you need a webserver to host your map. The "map starter kit" comes with a local webserver that you can use to test your map.
+
+In order to start the webserver, you will need [Node.JS](https://nodejs.org/en/). When it is downloaded, open your command line and from the directory of the map, run this command:
+
+    $ npm install
+
+This will install the local webserver.
+
+    $ npm run start
+
+This command will start the webserver and open the welcome page. You should see a page looking like this:
+
+<figure class="figure my-5">
+    <img src="images/start_kit_start_screen.png" class="figure-img img-fluid rounded" alt="" style="width: 70%" />
+    <figcaption class="figure-caption">The welcome page of the "map start kit"</figcaption>
+</figure>
+
+From here, you simply need to click the "Test this map" button to test your map in WorkAdventure.
+
+{.alert.alert-warning}
+The local web server can only be used to test your map locally. In particular, the link will only work on your computer. You cannot share it with other people.
+
+### Pushing the map
+
+When your changes are ready, you need to "commit" and "push" (i.e. "upload") the changes back to GitHub. Just wait a few minutes, and your map will be propagated automatically to the GitHub pages web-server.
+
+## Testing your map
+
+To test your map, you need to find its URL. There are 2 kinds of URLs in WorkAdventure:
+
+*   Test URLs are in the form `https://play.workadventu.re/_/[instance]/[server]/[path to map]`
+*   Registered URLs are in the form `https://play.workadventu.re/@/[organization]/[world]/[map]`
+
+Assuming your JSON map is hosted at "`https://myuser.github.io/myrepo/map.json`", then you can browse your map at "`https://play.workadventu.re/_/global/myuser.github.io/myrepo/map.json`". Here, "global" is a name of an "instance" of your map. You can put anything instead of "global" here. People on the same instance of the map can see each others. If 2 users use 2 different instances, they are on the same map, but in 2 parallel universes. They cannot see each other.
+
+This will connect you to a "public" instance. Anyone can come and connect to a public instance. If you want to manage invitations, or to perform some moderation, you will need to create a "private" instance. Private instances are available in "pro" accounts.
+
+<div class="card">
+    <div class="card-body">
+        <h3 id="need-some-help">Need some help?</h3>
+        <p>WorkAdventure is a constantly evolving project and there is plenty of room for improvement regarding map editing.</p>
+        <p>If you are facing any troubles, do not hesitate to open an "issue" in the
+            <a href="https://github.com/thecodingmachine/workadventure/issues" target="_blank">GitHub WorkAdventure account</a>.
+        </p>
+    </div>
+</div>

docs/maps/using-typescript.md

@@ -1,3 +1,4 @@
+{.section-title.accent.text-primary}
 # Using Typescript with the scripting API
 
 {.alert.alert-info}
@@ -57,7 +58,9 @@ In your map directory, start by adding a `package.json` file. This file will con
 
 You can now install the dependencies:
 
-    $ npm install
+```console
+$ npm install
+```
 
 We now need to add a Webpack configuration file (for development mode). This Webpack file will:
 
@@ -65,109 +68,116 @@ We now need to add a Webpack configuration file (for development mode). This Web
 *   Compile Typescript into Javascript and serve it automatically
 
 **webpack.config.js**
+```js
+const path = require('path');
+const webpack = require('webpack');
+const HtmlWebpackPlugin = require('html-webpack-plugin');
 
-    const path = require('path');
+module.exports = {
-    const webpack = require('webpack');
+    mode: 'development',
-    const HtmlWebpackPlugin = require('html-webpack-plugin');
+    entry: './src/index.ts',
-
+    devtool: 'inline-source-map',
-    module.exports = {
+    devServer: {
-        mode: 'development',
+        // The test webserver serves static files from the root directory.
-        entry: './src/index.ts',
+        // It comes with CORS enabled (important for WorkAdventure to be able to load the map)
-        devtool: 'inline-source-map',
+        static: {
-        devServer: {
+            directory: ".",
-            // The test webserver serves static files from the root directory.
+            serveIndex: true,
-            // It comes with CORS enabled (important for WorkAdventure to be able to load the map)
+            watch: true,
-            contentBase: '.',
-            host: 'localhost',
-            disableHostCheck: true,
-            headers: {
-                "Access-Control-Allow-Origin": "*",
-                "Access-Control-Allow-Methods": "GET, POST, PUT, DELETE, PATCH, OPTIONS",
-                "Access-Control-Allow-Headers": "X-Requested-With, content-type, Authorization"
-            }
         },
-        module: {
+        host: 'localhost',
-            rules: [
+        allowedHosts: "all",
-                {
+        headers: {
-                    test: /\.tsx?$/,
+            "Access-Control-Allow-Origin": "*",
-                    use: 'ts-loader',
+            "Access-Control-Allow-Methods": "GET, POST, PUT, DELETE, PATCH, OPTIONS",
-                    exclude: /node_modules/,
+            "Access-Control-Allow-Headers": "X-Requested-With, content-type, Authorization"
-                },
-            ],
-        },
-        resolve: {
-            extensions: [ '.tsx', '.ts', '.js' ],
-        },
-        output: {
-            filename: 'script.js',
-            path: path.resolve(__dirname, 'dist'),
-            publicPath: '/'
         }
-    };
+    },
+    module: {
+        rules: [
+            {
+                test: /\.tsx?$/,
+                use: 'ts-loader',
+                exclude: /node_modules/,
+            },
+        ],
+    },
+    resolve: {
+        extensions: [ '.tsx', '.ts', '.js' ],
+    },
+    output: {
+        filename: 'script.js',
+        path: path.resolve(__dirname, 'dist'),
+        publicPath: '/'
+    }
+};
+```
 
 We need to configure Typescript, using a `tsconfig.json` file.
 
 **tsconfig.json**
-
+```json
-    {
+{
-      "compilerOptions": {
+  "compilerOptions": {
-        "outDir": "./dist/",
+    "outDir": "./dist/",
-        "sourceMap": true,
+    "sourceMap": true,
-        "moduleResolution": "node",
+    "moduleResolution": "node",
-        "module": "CommonJS",
+    "module": "CommonJS",
-        "target": "ES2015",
+    "target": "ES2015",
-        "declaration": false,
+    "declaration": false,
-        "downlevelIteration": true,
+    "downlevelIteration": true,
-        "jsx": "react",
+    "jsx": "react",
-        "allowJs": true,
+    "allowJs": true,
-        "strict": true
+    "strict": true
-      }
+  }
-    }
+}
+```
 
 Create your entry point (the Typescript file at the root of your project).
 
 **src/index.ts**
+```typescript
+/// <reference path="../node_modules/@workadventure/iframe-api-typings/iframe_api.d.ts" />
 
-    /// <reference path="../node_modules/@workadventure/iframe-api-typings/iframe_api.d.ts" />
+console.log('Hello world!');
-
+```
-    console.log('Hello world!');
 
 The first comment line is important in order to get `WA` typings.
 
 Now, you can start Webpack in dev mode!
 
-    npm run start
+```console
+$ npm run start
+```
 
 This will automatically compile Typescript, and serve it (along the map) on your local webserver (so at `http://localhost:8080/script.js`). Please note that the `script.js` file is never written to the disk. So do not worry if you don't see it appearing, you need to "build" it to actually write it to the disk.
 
 Final step, you must reference the script inside your map, by adding a `script` property at the root of your map:
 
-<div>
+<figure class="figure">
-
+    <img src="images/script_property.png" class="figure-img img-fluid rounded" alt="" />
-<figure class="figure">![]({{url('img/docs/script_property.png')}})
+    <figcaption class="figure-caption">The script property</figcaption>
-
-<figcaption class="figure-caption">The script property</figcaption>
-
 </figure>
 
-</div>
-
 ### Building the final script
 
 We now have a correct development setup. But we still need to be able to build the production script from Typescript files. We are not going to use the development server in production. To do this, we will add an additional `webpack.prod.js` file.
 
 **webpack.prod.js**
+```javascript
+const { merge } = require('webpack-merge');
+const common = require('./webpack.config.js');
 
-    const { merge } = require('webpack-merge');
+module.exports = merge(common, {
-    const common = require('./webpack.config.js');
+  mode: 'production',
-
+  devtool: 'source-map'
-    module.exports = merge(common, {
+});
-      mode: 'production',
+```
-      devtool: 'source-map'
-    });
 
 This file will simply switch the Webpack config file in "production" mode. You can simply run:
 
-    $ npm run build
+```console
+$ npm run build
+```
 
 and the `script.js` file will be generated in the `dist/` folder. Beware, you will need to move it at the root of map for it to be read by the map.