New www.defold.com leveraging GitHub Pages and Jekyll+Liquid to generate a static site. The structure of the static site as well as many of the pages are stored in this repository. Some other parts of the site such as content of the learn section and the asset portal is hosted in other GitHub repositories:

• Assets - defold.com/assets -> github.com/defold/asset-portal
• Showcase - defold.com/showcase -> github.com/defold/games-showcase
• Learn
  • Manuals - defold.com/manuals -> github.com/defold/doc
  • Tutorials - defold.com/tutorials -> github.com/defold/doc
  • FAQ - defold.com/faq/faq -> github.com/defold/doc
  • Examples - defold.com/examples -> github.com/defold/examples
• Codepad - defold.com/codepad -> github.com/defold/codepad

The site uses the update.py script from this repository to update the site with updated content from external sources/repositories.

You need to make sure to have the following dependencies installed before using update.py:

• Python 3.x
• Requests (http requests)
• PyYAML, Markdown, Pygments

Install dependencies using:

pip3 install --user requests
pip3 install --user pyyaml
pip3 install --user markdown==3.4.1
pip3 install --user pygments==2.13.0

The update.py script should be run from a terminal. The syntax is as follows:

python3 update.py [--download] docs codepad refdoc examples asset-portal games-showcase

You can use this script when testing locally (see below). The script is also used by GitHub Actions when automatically updating the site when one of the external sources/repositories have changed (see below).

The script accepts the following options:

• --download - Download the required files for each command. If the option is omitted the files are expected to already exist on disk ready for processing.
• --githubtoken - GitHub authentication token when committing changes.

The script accepts the following commands:

• docs - Import manuals, tutorials and FAQ from github.com/defold/doc
• codepad - Import CodePad from github.com/defold/codepad
• refdoc - Import API reference from latest release at d.defold.com
• examples - Import examples from github.com/defold/examples
• asset-portal - Import Asset Portal content from github.com/defold/asset-portal
• games-showcase - Import Showcase content from github.com/defold/games-showcase
• commit - Commit changes to GitHub (for CI use)

The Showcase source of truth is defold/games-showcase. _data/games.json, _data/showcase_featured_full.json, and images/games are committed snapshots, like the Asset Portal data and images. Ordinary site builds use these snapshots without downloading showcase content. Showcase content changes trigger the games-showcase update; an explicit all update also refreshes it. Run python3 update.py --download games-showcase to refresh locally. This downloads the upstream archive, copies only new or changed referenced images, removes obsolete image files, and updates the catalog and featured list together. Unchanged images are reused without recompression.

It is recommended that you generate and test the site locally before pushing the changes to the repository. You generate and test the site locally by running serve.sh.

You need to make sure you have the following dependencies installed before attempting to generate the site locally using serve.sh:

• Ruby
• bundler gem
• Jekyll 4 (installed by Bundler)
• Pagefind (for search indexing)

Most macOS versions ship with Ruby preinstalled. It is however recommended that you install a separate Ruby version as you will very likely run into permission issues if trying to install any Ruby gems with the system version of Ruby.

The recommended approach is to use Homebrew to install Ruby:

If you don't have Homebrew installed, open a terminal window and install it:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

brew install ruby

Add Ruby to your PATH by adding this line to your shell profile (e.g. ~/.zshrc):

export PATH="/opt/homebrew/opt/ruby/bin:$PATH"

Then restart your terminal or run:

source ~/.zshrc

If you prefer to use rbenv for Ruby version management:

# Install rbenv
brew install rbenv

# Add rbenv to shell profile
echo 'eval "$(rbenv init -)"' >> ~/.zshrc

# Restart terminal or reload profile
source ~/.zshrc

# Install Ruby version specified in .ruby-version file
rbenv install $(cat .ruby-version)
rbenv local $(cat .ruby-version)

The site uses bundler to manage gem dependencies. Install bundler first, set config directory, then install all dependencies:

gem install bundler
bundle config set --local path 'vendor/bundle'
bundle install

Note: Jekyll supplies its required csv dependency. The logger gem is listed explicitly for compatibility with Ruby versions where it is no longer part of the default installation.

The site uses Pagefind for search functionality. Install it using:

pip3 install "pagefind[extended]==1.5.2"

The serve.sh script will automatically check for Pagefind installation and provide installation instructions if missing.

Launch/serve the site locally:

./serve.sh

Once the site has been built you can test it by pointing your browser to localhost:4000.

Note: If you're using Homebrew Ruby, you may need to set the PATH in your terminal session:

export PATH="/opt/homebrew/opt/ruby/bin:$PATH"
./serve.sh

You can use the update.py script to pull in and process content from external sources (docs, asset portal etc)

The API reference has three engine release channels: Stable (the released engine), Beta (the upcoming release under testing), and Alpha (ongoing development). Each channel reads its own snapshot from _data/ref/<channel>/.

Stable pages use /ref/<api>/. The old /ref/stable/<api>/ URLs redirect there, preserving query strings and function anchors. Beta and Alpha use /ref/beta/<api>/ and /ref/alpha/<api>/. update.py refdoc regenerates these pages, redirects, and navigation links together.

The channel selector below API search opens the same API in the selected channel, or its category overview if that API is unavailable. update.py --download refdoc also saves the current engine versions from https://d.defold.com/<channel>/info.json to _data/engine_versions.json for the tooltips, engine API page titles, and visible Lua API version labels (for example, Version: stable (1.13.1)). Local imports without --download retain those versions. Extension APIs have independent releases and do not show the engine channel selector or engine version numbers.

Copy the refdoc.zip to the main folder:

cp $DYNAMO_HOME/share/ref-doc.zip refdoc_alpha.zip
cp $DYNAMO_HOME/share/ref-doc.zip refdoc_beta.zip
cp $DYNAMO_HOME/share/ref-doc.zip refdoc_stable.zip
./update.py refdoc
./serve.sh

The single /sitemap.xml includes canonical HTML pages. API references and category overviews in all three channels are indexable and included, along with extension APIs. Each channel uses its own canonical URLs, so APIs that are not available in Stable can still be discovered. The main navigation and general documentation links use Stable by default. Engine API page titles identify the channel and engine version; Google determines which version appears in search results.

_includes/search_engine_metadata.html shares this policy between page heads and the sitemap. Legacy API aliases point to the corresponding reference in their channel and remain excluded; redirect pages are also excluded. Google indexing is independent of Pagefind: pagefind_exclude only controls internal search. Set noindex: true in front matter to exclude another page from search engines and the sitemap, or sitemap: false to omit it from the sitemap only. A page with a different canonical URL is omitted from the sitemap.

Internal API search indexes canonical references in all three channels and extension APIs. Crawling remains allowed in robots.txt so search engines can read indexing instructions.

Sitemap lastmod values come only from an explicit last_modified_at front-matter date representing the last significant content update. Unknown update dates are omitted; publication dates and build timestamps are not substituted. The sitemap does not emit priority or changefreq.

By setting the DM_DOC_DIR environment variable, you can load the documentation directory from your local folder:

DM_DOC_DIR=/Users/username/work/doc python3 update.py docs

The site uses GitHub Actions to automatically trigger update.py when an external source/repository has been updated. CI then builds the Jekyll site, generates the Pagefind index, and deploys the built _site to GitHub Pages via actions/deploy-pages. Ensure the repository Pages settings use “GitHub Actions” for build & deployment.

The script is also triggered once every hour to update the asset portal star count for GitHub hosted assets. The following workflows/jobs have been set up using GitHub Actions:

• Update site - on change in external repository (triggered using the repository_dispatch event)
  • Asset-portal - Triggered from asset-portal workflow on change.
  • Games-showcase - Triggered from the games-showcase publish workflow after validated game data, image, order, or featured-list changes reach master, or when manually dispatched.
  • Docs (manuals, tutorials, faq) - Triggered from doc workflow on change.
  • Docs (examples) - Triggered from examples workflow on change.
  • Codepad - Triggered from codepad workflow on change.

The site search is powered by Pagefind, a static site search library. Pagefind automatically generates a search index during the site build process and provides a fast, client-side search interface with filtering and metadata support.

Search includes Stable, Beta, and Alpha API references, with channel and engine version labels. Existing Pagefind content and section weights are multiplied by 1.0 for Stable, 0.9 for Beta, and 0.8 for Alpha. This favors Stable while preserving relevance and staying within Pagefind's maximum weight of 10. Legacy aliases, redirects, and API category overviews remain excluded.

Search always selects one API channel, defaulting to Stable. The API sidebar defaults to its current channel. Both search interfaces use three channel buttons backed by Pagefind's filters; on the full search page they appear above the Section filters. Each button counts matching pages in the API section across all channels, independently of the current channel and Section selections. The channel follows both form submissions and “View all results” links to /search?q=…&channel=beta. Manuals, tutorials, extensions, and other unversioned content belong to all three filter values, so selecting an API channel keeps that content visible.

Functionality for searching and marking within a single page using Mark.js.

All website-owned author information lives in: _data/authors.json.

You can change a contributor's canonical name, GitHub account, aliases, bio, avatar, links, or support links. Asset and example attribution remains in the upstream defold/asset-portal and defold/examples repositories.

Running either the asset-portal or examples update resolves those upstream names through _data/authors.json, writes the canonical name and id into the generated asset and example data, and rebuilds the lightweight pages under authors/. Author pages read their asset and example cards from the existing generated catalogs at Jekyll build time, so no contribution lists are copied into author profile data.

Aliases are accepted only while importing upstream attribution. They preserve old author URLs and let renamed contributors resolve to one canonical profile; they are not emitted as public author names. An optional id should only be used when a renamed profile must retain an existing hash URL; normally the id is derived automatically from name.

This site uses the following assets:

• Octicons