Build process wip. TOC and document metadata. Proofreading and fixing docs.

docs/en/manuals/2dgraphics.md

@@ -34,8 +34,8 @@ You need to populate an _Atlas_ before you can use it. As soon as you have added
 Your atlas has now been populated with images (and animations) it can be used as a graphics source to other components in Defold (see Sprite below and the ParticleFX guide).
 
 1. Import your image files as described above.
-2. Select [[New ▸ Atlas File]]{.menu} from the context menu in the Project Explorer.
-3. Select *Add Images* from the context menu in the Outline.
+2. Select <kbd>New ▸ Atlas File</kbd> from the context menu in the Project Explorer.
+3. Select <kbd>Add Images</kbd> from the context menu in the Outline.
 
 A dialog opens from where you can find and select the images you want to add to the Atlas. Note that you can filter the image files and select multiple files at once.
 
@@ -46,11 +46,11 @@ A dialog opens from where you can find and select the images you want to add to
 
 You can define flip-book animations of selected sub-images in an atlas:
 
-- Select *Add Animation Group* from the context menu in the Outline.
-- Select *Add Images* from the context menu of the created animation group and choose the images that you want as frames of the animation.
+- Select <kbd>Add Animation Group</kbd> from the context menu in the Outline.
+- Select <kbd>Add Images</kbd> from the context menu of the created animation group and choose the images that you want as frames of the animation.
 - Adjust the *Properties* for the animation as needed.
 
-You can reorder the images in the Outline by dragging them, if needed. You can also easily create duplicates by copying and pasting (From the *Edit* menu, the right click context menu or keyboard shortcuts) images in the outline. Select an animation and press *Space* on your keyboard to preview the animation.
+You can reorder the images in the Outline by dragging them, if needed. You can also easily create duplicates by copying and pasting (From the <kbd>Edit</kbd> menu, the right click context menu or keyboard shortcuts) images in the outline. Select an animation and press <kbd>Space</kbd> on your keyboard to preview the animation.
 
 ## Creating a Tile Source
 
@@ -83,7 +83,7 @@ To define an animation in a Tile Source each frame must correspons to one tile (
 
 ![Tile Source add animation](images/2dgraphics/2dgraphics_tilesource_animation.png)
 
-You can easily add more animations to the Tile Source by selecting *Add Animation* in the context menu that can be accessed by right clicking the root *Tile Source* in the Outline view.
+You can easily add more animations to the Tile Source by selecting <kbd>Add Animation</kbd> in the context menu that can be accessed by right clicking the root *Tile Source* in the Outline view.
 
 ![Tile Source animation](images/2dgraphics/2dgraphics_tilesource_add_animation.png)
 
@@ -107,7 +107,7 @@ go.animate("wand", "euler", go.PLAYBACK_ONCE_FORWARD, vmath.vector3(0, 0, -70),
 
 It is actually possible to dynamically alter the scale of Sprite components in a non uniform way. This is a special feature that may feel odd when you try to construct a mental model for how game objects and components are related to each other and how to work with them.
 
-Sprites have a property "scale" which is of type `vmath.vector3`. You can animate the components separately:
+Sprites have a property `scale` which is of type `vmath.vector3`. You can animate the components separately:
 
 ```lua
 go.animate("my_object#sprite", "scale.x", go.PLAYBACK_ONCE_FORWARD, 1.5, go.EASING_INOUTSINE, 2)
@@ -118,8 +118,8 @@ go.animate("my_object#sprite", "scale.x", go.PLAYBACK_ONCE_FORWARD, 1.5, go.EASI
 Sprite components are used to add graphics and flip-book animations to game objects. They are typically used to create characters and props. Creating a Sprite component is very straightforward:
 
 - Create (or open) the game object the Sprite should belong to.
-- From the Game Object context menu in the Outline, select *Add Component*.
-- Choose "Sprite".
+- From the Game Object context menu in the Outline, select <kbd>Add Component</kbd>.
+- Choose *Sprite*.
 - Specify in the Sprite's *Image* property which Tile Source or Atlas the Sprite should use.
 - Specify in the Sprite's *Default Animation* property which animation it should play by default.
 
@@ -136,27 +136,24 @@ The *Blend Mode* property defines how the sprite should be blended with the grap
 Alpha
 : Normal blending: a~0~ * rgb~0~ + (1 - a~0~) * rgb~1~
 
-
 Add
 : Brighten the background with the color values of the corresponding sprite pixels: rgb~0~ + rgb~1~
 
-
-Add Alpha
+Add Alpha (deprecated!)
 : Brighten the background with the corresponding visible sprite pixels: a~0~ * rgb~0~ + rgb~1~
 
-
 Multiply
 : Darken the background with values of the the corresponding sprite pixels: rgb~0~ * rgb~1~
 
 ## Sprite Shading
 
-The default sprite shading files are located under "/builtins/material/sprite.*" in your project. The default shading performs a regular texture lookup, but also has a tint (a fragment shader constant) which is multiplied with the texture color.
+The default sprite shading files are located under */builtins/material/sprite.\** in your project. The default shading performs a regular texture lookup, but also has a tint (a fragment shader constant) which is multiplied with the texture color.
 
 To obtain effects like flashing a sprite white when it is hit, you can implement custom shading. To set a custom shading for your sprites, follow these steps:
 
-- Copy the files under "/builtins/material/sprite.*" into one of your project directories (you can't modify the content of the "builtins"-directory). This is not mandatory but makes the process easier.
-- Open the copied "sprite.material" file and remap the shader files (.vp and .fp) to your own copies.
-- Edit the .vp and .fp copies as you please. If you introduce shader constants, they must also be declared in the material file.
+- Copy the files under */builtins/material/sprite.\** into one of your project directories (you can't modify the content of the *builtins*-directory). This is not mandatory but makes the process easier.
+- Open the copied *sprite.material* file and remap the shader files (*.vp* and *.fp*) to your own copies.
+- Edit the *.vp* and *.fp* copies as you please. If you introduce shader constants, they must also be declared in the material file.
 - Open your sprite and specify your new material in the Properties.
 - To set a shader constants while the game is running, use the functions [`sprite.set_constant()`](/ref/sprite#sprite.set_constant) and [`sprite.reset_contant()`](/ref/sprite#sprite.reset_constant).
 
@@ -167,15 +164,15 @@ A Tile Map is a component that allows you to assemble, or _paint_, tiles from a
 ## Painting Tiles
 
 - Open the Tile Map you want to work in.
-- Make sure that there are no flagged issues in the Property or Outline view.
-- Select or create a Layer to paint on in the Outline view.
-- Select a tile to use as brush (press *Space* to show the tile palette)
+- Make sure that there are no flagged issues in the *Property* or *Outline* view.
+- Select or create a Layer to paint on in the *Outline* view.
+- Select a tile to use as brush (press <kbd>Space</kbd> to show the tile palette)
 
 ![Painting tiles](images/2dgraphics/2dgraphics_tilemap.png)
 
 ## Picking Tiles
 
-You can also pick tiles directly from the Tile Map to use as a brush. Hold *Shift* and click a tile to pick it up as the current brush. When holding *Shift* you can also click and drag to select a block of tiles to use as a larger brush.
+You can also pick tiles directly from the Tile Map to use as a brush. Hold <kbd>Shift</kbd> and click a tile to pick it up as the current brush. While holding <kbd>Shift</kbd> you can also click and drag to select a block of tiles to use as a larger brush.
 
 ![Picking tiles](images/2dgraphics/2dgraphics_tiles_pick.png)
 
@@ -183,10 +180,10 @@ You can also pick tiles directly from the Tile Map to use as a brush. Hold *Shif
 
 The Eraser tool is used to erase painted tiles. To select the Eraser, you can either:
 
-- Select it from the Tile Map menu
-- Press *Backspace*
-- Click the active tile again in the tiles palette
-- Pick any empty cell on the Tile Map
+- Select it from the <kbd>Tile Map</kbd> menu.
+- Press <kbd>Backspace</kbd>.
+- Click the active tile again in the tiles palette.
+- Pick any empty cell on the Tile Map.
 
 ## Attaching Physics
 
@@ -210,7 +207,7 @@ msg.post("/level#tilemap", "set_tile", { layer_id = hash("layer1"), position = d
 To add a Tile map to your game:
 
 1. Create a game object to hold the Tile Map component. The game object can be in a file or created directly in a collection
-2. Right-click the root of the game object and select [menuseq]#Add component from file#
+2. Right-click the root of the game object and select <kbd>Add component from file</kbd>
 3. Select the Tile Map file
 
 The game object now contains the Tile Map and you can place or spawn the game object wherever you want it.

docs/en/manuals/android.md

@@ -1,6 +1,9 @@
-= Android development
+---
+title: Defold development on the Android platform
+brief: This manual describes how to build and run Defold applications on Android devices
+---
 
-This document describes how to build and run Defold applications on Android devices.
+# Android development
 
 Android development differs from iOS development in that the devices give free access to upload content. It is very easy to build a version of your game and copy it onto an Android device. You can as easily put the development engine on a device for iterative development on the device over wifi.
 
@@ -18,33 +21,33 @@ You can find more information from the [Google Play developer console](https://p
 
 The `adb` command line tool is an easy to use and versatile program that is used to interact with Android devices. You can download and install `adb` as part of the Android SDK package, for Mac, Linux or Windows.
 
-Download the Android SDK from: http://developer.android.com/sdk/index.html. You find the `adb` tool in <sdk>/platform-tools/. Alternatively, platform specific packages can be installed through respective package managers.
+Download the Android SDK from: http://developer.android.com/sdk/index.html. You find the *adb* tool in *<sdk>/platform-tools/*. Alternatively, platform specific packages can be installed through respective package managers.
 
 On Ubuntu Linux:
 
-----
+```sh
 $ sudo apt-get install android-tools-adb
-----
+```
 
 On Fedora 18/19:
 
-----
+```sh
 $ sudo yum install android-tools
-----
+```
 
 On Mac OS X (Homebrew)
 
-----
+```sh
 $ brew install android-platform-tools
-----
+```
 
 You can veryfy that `adb` works by connecting your Android device to your computer via USB and issue the following command:
 
-----
+```sh
 $ adb devices
 List of devices attached
 31002535c90ef000    device
-----
+```
 
 If your device does not show up, verify that you have enabled *USB debugging* on the Android device. Open the device *Settings* and check *Developer options* (or *Development*).
 

docs/en/manuals/facebook.md

@@ -22,7 +22,7 @@ To develop for Facebook requires that you sign up as a Facebook developer. This
 
 ## Creating a Facebook app
 
-The next step is to create a Facebook application. The [menuseq]#My Apps# menu in the corner lists your apps, and there is a choice [menuseq]#Add a New App#.
+The next step is to create a Facebook application. The <kbd>My Apps</kbd> menu in the corner lists your apps, and there is a choice <kbd>Add a New App</kbd>.
 
 ![Add new app](images/facebook/add_new_app_menu.png)
 

docs/en/manuals/font.md

@@ -7,7 +7,7 @@ Font files in TrueType, OpenType or BMFont format can be added to your project a
 
 ## Creating a font
 
-To create a font for use in Defold, simply create a new Font file by selecting *File > New > Font File* (or right click in the *Project Explorer* and create the file).
+To create a font for use in Defold, simply create a new Font file by selecting <kbd>File ▸ New ▸ Font File</kbd> (or right click in the *Project Explorer* and create the file).
 
 ![Create font](images/font/fonts_create.png)
 
@@ -68,9 +68,8 @@ Shadow rendering of fonts is currently disabled by default because of performanc
 *output_format*
 : This property controls the type of font that is generated.
 
-+
-* `TYPE_BITMAP`. For OTF and TTF files, the imported font is converted into a font sheet texture where the bitmap data is used to render text nodes. The color channels are used to encode different aspects of the font, such as the face shape, outline and drop shadow. The preview shows the raw font texture with the font face in the red channel, the outline in the green channel and shadow in the blue channel. The pixel density of the font is fixed so it will look good in its generated size or scaled down. Bitmap fonts are very fast to render but size limited--scaling up a bitmap font quickly creates artifacts.
-* `TYPE_DISTANCE_FIELD` The imported font is converted into a font sheet texture where the pixel data represent not screen pixels but distances to the font edge. See below for details.
+  - `TYPE_BITMAP`. For OTF and TTF files, the imported font is converted into a font sheet texture where the bitmap data is used to render text nodes. The color channels are used to encode different aspects of the font, such as the face shape, outline and drop shadow. The preview shows the raw font texture with the font face in the red channel, the outline in the green channel and shadow in the blue channel. The pixel density of the font is fixed so it will look good in its generated size or scaled down. Bitmap fonts are very fast to render but size limited---scaling up a bitmap font quickly creates artifacts.
+  - `TYPE_DISTANCE_FIELD` The imported font is converted into a font sheet texture where the pixel data represent not screen pixels but distances to the font edge. See below for details.
 
 *all_chars*
 : If you set this property to `true` all glyphs available in the source file are included in the output.
@@ -111,7 +110,7 @@ To create a BMFont, you need to use a tool that can generate the appropriate fil
 
 ## Distance field fonts
 
-To create a distance field font, simply select "TYPE_DISTANCE_FIELD" as *output_format*. This creates a distance field map for the font. When the engine renders the font, a special shader is required to interprets the distance data and use that to create a sharp font edge. Distance field fonts are more resource intensive than bitmap fonts, but allow for much greater sizing flexibility.
+To create a distance field font, simply select `TYPE_DISTANCE_FIELD` as *output_format*. This creates a distance field map for the font. When the engine renders the font, a special shader is required to interprets the distance data and use that to create a sharp font edge. Distance field fonts are more resource intensive than bitmap fonts, but allow for much greater sizing flexibility.
 
 ![Distance field font](images/font/fonts_distance_field.png)
 

docs/en/manuals/gui-templates.md

@@ -1,7 +1,10 @@
+---
+title: GUI templates manual
+brief: This manual explains the Defold GUI template system that is used to create reusable visual GUI components based on shared templates or 'prefabs'.
+---
+
 Templates
 =========
-:location: documentation manuals gui
-:type: manual
 
 GUI templates provide a simple but powerful mechanism to create reusable visual GUI components based on shared templates or "prefabs". This manual explains the feature and how to use it.
 
@@ -21,6 +24,8 @@ Select the GUI scene file to use as template, in this case "button.gui". You can
 
 ![Node instances](images/gui-templates/gui-templates-instances.png)
 
+The template itself is represented in the node tree with an item: "button" and "button1" above. Even though they look like they are nodes, they *are not*. Adding a template to a scene adds all the template nodes. There is no "template root node" or similar. If you need a root node to manipulate all nodes in a template, you have to add the root node to the template scene.
+
 ## Overloading properties
 
 Each instance node can overload any of the properties set in the template. Simply mark the node you wish to edit and change the property you want to alter. Nodes that has any overloaded properties are marked green in the *Outline* view. An overloaded property is marked blue. Click the blue property name to reset the property's value to the default.

docs/en/test.md

@@ -1,10 +1,17 @@
+---
+title: Defold documentation typography test
+brief: This document uses all Markdown features (Commonmark + extensions) that the Defold docs use.
+---
+
 # Defold documentation typography
 
 All defold manuals and tutorials are written in Markdown. This document outlines how to use the various formatting for a consistent look on all documents.
 
 Try to write as talking to the user. Keep the language direct and active and refrain from stating opinions unless it is important to the matter. Try to write paragraphs that flow and do not break them unnecessarily.
 
-You do have some typographic markers to your disposal. The simplest one is the *emphasis* marker. It puts some stress to a word, marking it as important. This marker should also be used to call attention to specific things that the user can encounter in Defold, like the names of properties, buttons etc. For example, a sprite component's *Position*, a button that says *Save...* etc. Do not use the **bold text** emphasis. Do not ***ever*** mark anything with both bold and emphasis.
+You do have some typographic markers to your disposal. The simplest one is the *emphasis* marker. It puts some stress to a word, marking it as important. This marker should also be used to call attention to specific things that the user can encounter in Defold, like the names of properties, buttons etc. For example, a sprite component's *Position*, a button that says *Save...* etc. File names are also typed like that: *game.project* or *main/images/logo.png*.
+
+Do not use the **bold text** emphasis. Do not ***ever*** mark anything with both bold and emphasis.
 
 Generally, when using quotes you can type straight quotes (`""`) and they get automatically converted to "nice typographically correct quotes". Also, the en and em-dashes are nice things to be able to type easily. You do that by typing `--` for en-dash and `---` for em-dash. So now you can get nicely typeset numeric intervals like 23--24, and if you want an em-dash as punctuation in a sentence---that's easy too. Just remember not to put spaces around them. A nice ellipsis character is also automatically inserted whenever you type more than two spaces in a row...
 

docs/sass/defold-md.sass

@@ -8,7 +8,7 @@
   font-style: normal
 
 // Colors
-$text-black: #13234a
+$text-black: #282c34
 $text-white: #d1d1d1
 $dark-grey: #282c34
 $light-grey: #e3e4e5
@@ -17,6 +17,7 @@ body
   font-family: Source Sans Pro, sans-serif
   color: $text-black
   line-height: 1.44em
+  font-size: 1.1em
 
 .documentation
   position: relative
@@ -60,9 +61,14 @@ body
   img
     max-width: 100%
 
-  p img
+  img
     margin: 1.6em 0
 
+  img:only-child
+    display: block
+    margin-left: auto
+    margin-right: auto
+
   .anchor
     display: block
     position: relative
@@ -80,6 +86,7 @@ body
     position: relative
 
   .sidenote
+    line-height: 1.1em
     position: absolute
     right: -18em
     width: 14em

gulpfile.js

@@ -6,7 +6,6 @@ var gutil = require('gulp-util');
 var tap = require('gulp-tap');
 var hljs = require('highlight.js')
 var server = require('gulp-server-livereload');
-var wrapper = require('gulp-wrapper');
 var sass = require('gulp-sass');
 var minify = require('gulp-cssnano');
 var del = require('del');
@@ -16,6 +15,7 @@ var hljs = require('highlight.js');
 
 var print = require('gulp-print');
 
+var frontmatter = require('front-matter');
 var markdown = require('markdown-it');
 var md_attrs = require('markdown-it-attrs');
 var md_container = require('markdown-it-container');
@@ -49,7 +49,6 @@ md.use(md_deflist);
 md.use(md_attrs);
 md.use(md_sub);
 md.use(md_sup);
-
 md.use(md_container, 'sidenote', { render: rendernote });
 md.use(md_container, 'important', { render: rendernote });
 
@@ -72,7 +71,14 @@ function slugname(str) {
 // Add anchors to all headings.
 md.renderer.rules.heading_open = function (tokens, idx, options, env, self) {
     var tag = tokens[idx].tag;
-    var slug = slugname(tokens[idx + 1].content);
+    var title = tokens[idx + 1].content
+    var slug = slugname(title);
+    // Add TOC entry
+    if(!("toc" in env) ) {
+        env.toc = [];
+    }
+    var level = tag.match(/^h(\d+)$/)[1];
+    env.toc.push({ entry: title, slug: slug, level: level });
     return '<a name="' + slug + '" class="anchor"></a>' +
             '<' + tag + '>';
 };
@@ -87,26 +93,55 @@ md.renderer.rules.heading_close = function (tokens, idx, options, env, self) {
         return '</' + tag + '>';
 };
 
-function markdownToHtml(file) {
-    var result = md.render(file.contents.toString());
-    file.contents = new Buffer(result);
+// Output preview html documents
+function markdownToPreviewHtml(file) {
+    var data = frontmatter(file.contents.toString());
+    // Inject some styling html for the preview. The built htmls are clean.
+    var head = '<html><head><link type="text/css" rel="stylesheet" href="/defold-md.css"></head><body>\n';
+    head += '<div class="documentation">';
+    var foot = '</div></body></html>\n';
+    var html = head + md.render(data.body) + foot;
+    file.contents = new Buffer(html);
     file.path = gutil.replaceExtension(file.path, '.html');
     return;
 }
 
+// Build document json for storage
+function markdownToJson(file) {
+    var data = frontmatter(file.contents.toString());
+    var toc = {};
+    data.html = md.render(data.body, toc);
+    data.toc = toc;
+    file.contents = new Buffer(JSON.stringify(data));
+    file.path = gutil.replaceExtension(file.path, '.json');
+    return;
+}
+
+// Build docs
+gulp.task('build', ['clean', 'assets'], function () {
+    return gulp.src('docs/**/*.md')
+        .pipe(tap(markdownToJson))
+        .pipe(print())
+        .pipe(gulp.dest("build"));
+});
+
+gulp.task('assets', [], function() {
+    return gulp.src(['docs/**/*.{png,jpg,svg,gif}'])
+        .pipe(gulp.dest("build"));
+});
+
 // Watch for changes in md files and compile new html
 gulp.task('watch', function () {
+    mkdirp('build/preview');
 
-    mkdirp('build');
-
-    gulp.src('build')
+    gulp.src('build/preview')
         .pipe(server({
             livereload: true,
             open: true,
 
             directoryListing: {
                 enable: true,
-                path: 'build'
+                path: 'build/preview'
             }
         }));
 
@@ -118,22 +153,13 @@ gulp.task('watch', function () {
 
     gulp.src('docs/**/images/**/*.*')
         .pipe(watch('docs/**/images/**/*.*'))
-        .pipe(gulp.dest("build"));
-
-    // Inject some styling html for the preview. The built htmls are clean.
-    var inj_head = '<html><head><link type="text/css" rel="stylesheet" href="/defold-md.css"></head><body>\n';
-    inj_head += '<div class="documentation">';
-    var inj_foot = '</div></body></html>\n';
+        .pipe(gulp.dest("build/preview"));
 
     return gulp.src('docs/**/*.md')
         .pipe(watch('docs/**/*.md'))
-        .pipe(tap(markdownToHtml))
-        .pipe(wrapper({
-            header: inj_head,
-            footer: inj_foot,
-            }))
+        .pipe(tap(markdownToPreviewHtml))
         .pipe(print())
-        .pipe(gulp.dest("build"));
+        .pipe(gulp.dest("build/preview"));
 });
 
 gulp.task('clean', [], function() {
@@ -145,5 +171,5 @@ gulp.task('sass', [], function() {
         .pipe(plumber())
         .pipe(sass())
         .pipe(minify())
-        .pipe(gulp.dest('build'))
+        .pipe(gulp.dest('build/preview'))
 });

package.json

@@ -4,6 +4,7 @@
   "version": "3.2.8",
   "dependencies": {
     "del": "^2.2.2",
+    "front-matter": "^2.1.2",
     "gulp": "^3.9.1",
     "gulp-cssnano": "^2.1.2",
     "gulp-plumber": "^1.1.0",
@@ -13,7 +14,6 @@
     "gulp-tap": "^0.1.3",
     "gulp-util": "^3.0.8",
     "gulp-watch": "^4.3.6",
-    "gulp-wrapper": "^1.0.0",
     "highlight.js": "^9.10.0",
     "markdown-it": "^8.3.1",
     "markdown-it-attrs": "^0.8.0",