Creating custom templates

📝Creating custom templates

A custom template is a npm package composed by a template.json, one or more HTML file with a *.njk extension and all the resources files (CSS, Javascript, fonts, images, etc).

Example of a template folder:

• my-template/
  • package.json
  • template.json
  • src/
    • index-scripts.njk
    • index-folder.njk
    • helper-files.njk
    • another-template-files.njk
  • css/
    • bootstrap.css
    • styles.css
  • js/
    • main.js

Creating a package.json file

First, create a folder named docs_gm-YOURTEMPLATENAME. For example: if your template name is red-wave, then your folder name (and package name) must be docs_gm-red-wave. And from the comand line:

npm init

Follow the instructions.

• The name of the package must be your folder name. For example: docs_gm-red-wave.
• The main file must be template.json.
• In the keywords section, add at least one keyword that is docs_gm.
• All the other values can be anything you want.

When you FINISH creating your template following this document, then you can use npm publish to publish the template on the npm registry.

If you want to test your template while you are developing it, use npm link to simulate that your package is installed on the system.

Then, create your template.json file:

template.json

The template.json file describes your template, and each design that your template supports.

{
    "name": "My Awesome template",
    "author": "Your name",
    "description": "A short description for your template.",
    "web": "Your web or github link",
    "copy": ["css/**/*", "js/**/*"],
    "pages": {
        "script": "src/script.njk",
        "folder": "src/folder.njk"
    }
}

Template

• "name": {string} (required) The display name of the template. It can be shown on the screen. Examples: "My super awesome template"
• "author": {string} (required) Is your name, or the name of the person who made the template.
• "description": {string} (required) A short template description.
• "web": {string} (required) Your website URL or github/repo link
• "copy": {array of strings} (optional) An array of files to copy for this design. The array can be a glob. More info about globs here. You can also use negated globs. If omitted, the default for the "copy" will be ["**/*", "!template.json", "!*.njk", "!package.json"]. (All files and folders will be copied except for template.json, package.json and all files with *.njk extension).

Pages

• "script": {string} (required) The path of the *.njk file that will be used to render each script.
• "folder": {string} (required) The path of the *.njk file that will be used to render each folder.

Template Pages

Each page is a *.njk file, that is a simple HTML file that uses Nunjucks templating. You can name your template pages files however you want. If you want autocomplete options for Nunjucks tags in your text editor, you can download your preferred editor plugin.

INFO: docs_gm provides a number of Templates you can inspect to learn about. For example, you can inspect the code for the docs_gm-basic included template from here

You can use any tag supported by Nunjucks inside you HTML:

<h1>Welcome to the {{ project.name }} documentation!</h1>
<p>This is the documentation for the {{ script.name }} script.</p>

Will be rendered as:

<h1>Welcome to the My Awesome Project documentation!</h1>
<p>This is the documentation for the scr_my_super_script script.</p>

For example, if you want to show a list with all the scripts name to create for example a Table of contents, you can use:

<h1>Table of contents</a>
<ul>
    {% for script in project.scripts.all %}
        <li>
            <a href="#{{ script.name }}">{{ script.name }}</a>
        </li>
    {% endfor %}
</ul>

As you can see, you can iterate over an array to access all the scripts.

However, it is highly advisable for you to ckeck the included template to learn from it.

Template exposed global variables

When rendering a template, docs_gm exposes a set of global variables that you can use:

• project: {DocProject} The DocProject object representing the GameMaker Project that you are creating the documentation for.
• resource: {DocResource} A DocResource object (DocFolder or DocScript) representing the SINGLE game maker resource that your must document in the current template page.
• script: {DocScript} If the page that is currently being rendered is a script page, this global variable will contain a reference to the current script you must document. Otherwise, it will be null.
• folder: {DocFolder} If the page that is currently being rendered is a folder page, this global variable will contain a reference to the current folder you must document. Otherwise, it will be null.

See the documentation for DocResource for more information.

Also, the following global functions are defined:

• linkTo(resource) {Function} It will generate a relative link to the specified script or folder page. For example:

<a href="{{ linkTo(script) }}">{{ script.name }}</a>

Will be rendered as:

<a href="../path/to/resource/scr_my_script_name.html">scr_my_script_name</a>

• asset(path) {Function} This function generates an url to the asset (css/js/image) file. For example:

<link href="{{ asset('css/styles.css') }}" rel="stylesheet">

Will be rendered as:

<link href="../path/to/css/styles.css" rel="stylesheet">

DocProject

Represents the current GameMaker project that you are documenting. This object has the following properties:

• name: { string } The name of the GameMaker project in a readable format. You can use it for titles, or descriptions inside your documentation.
• root: { DocFolder } The root folder for the documentation. Normally is the "scripts" folder, but it can be any other folder, for example the root folder where you put all the scripts for your GameMaker Marketplace Extension.

DocResource

Base type that represents a generic game maker resource (or folder) on the project

• type: { string } It will the type of resource. If for some reason docs_gm have troubles identifying the type of the resource the value will be "resource". The possible values are: "script", "folder" or "resource".
• name: { string } The name of the resource. Examples: "spr_wall", "my_super_folder", "scr_walljump".
• parent { DocFolder | null } The parent folder. For the project.root folder (for example the root "scripts" folder), this value is allways null.
• fullpath { string } The fullpath of the resource, relative to the project.root folder. For example: "inventory_system/drawing/draw_inventory"
• project { DocProject } The project object asociated to this resource
• anchor { string } A unique identifier for this resource. You must use this to generate id for the anchor links. For example <h1 id="{{ script.anchor }}">{{ script.name }}</h1>
• next { DocResource | null} The next sibling element in the parent folder or null if it is the last sibling.
• prev { DocResource | null} The previous sibling element in the parent folder or null if it is the first sibling.

DocFolder

DocScript extends DocResource. So it also have the properties described in the DocResource section.

Represents a single GameMaker folder or subfolder on the resource tree.

• description: { string } The description of the folder if present. (The default is an empty string ""). See the @module tag for more info about folder descriptions.
• children: { DocResource[] } An array with all the direct children of that folder.
• all: { DocResource[] } Returns an array that contains ALL the DocResources including NESTED resources recursively. For example. If you have a parent folder with a script1 and a subfolder with script2 and script3, parentFolder.all will return [DocScript (script1), DocScript (script2), DocScript (script3)]
• isParentOf(resource) { function, returns boolean} A function that returns true or false if the specified resource is a direct or indirect child of this folder.

DocScript

DocScript extends DocResource. So it also have the properties described in the DocResource section.

Represents a single script of the GameMaker project.

• description: { string } The description of the script.
• params: { DocParam[] } An array of DocParams objects. Representing each parameter or argument of the script.
• returns: { DocReturns | null } A DocReturns object, representing the returned value of the script. (or null if the script has no @returns documentation)
• examples: { DocExample[] } An array of DocExample objects. Representing each usage example code provided for the script.
• private: { boolean } true or false depending if the script is a private script or not (can be marked with the @private JSDoc or with a script name starting with underscore).
• undocumented: { boolean } true if is undocumented script, false if not.
• function: { string } The function name. Is declared in the documentation with the @function tag. Normally, is the same as the name.

DocParam

Represents a single parameter or argument of a script.

• name: {string} The name of the argument.
• type: {string} The type of the argument.
• description: {string} The description of the argument
• optional: {boolean} true or false depending if the argument is marked as optional, or not.

DocReturns

Represents a returned value of a script.

• type: {string} The type of the returned value.
• description: {string} The description of the returned value

DocExample

Represents a single script usage Example

• code: {string} The code for the Example
• caption: {string} The example caption (not supported for now, wait for a next update)