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 - www.defold.com/assets -> github.com/defold/awesome-defold
- Learn
- Manuals - www.defold.com/manuals -> github.com/defold/doc
- Tutorials - www.defold.com/tutorials -> github.com/defold/doc
- FAQ - www.defold.com/faq -> github.com/defold/doc
- Examples - www.defold.com/examples -> github.com/defold/examples
- Codepad - www.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
- Lunr.py (search)
- Requests (http requests)
Install lunr.py and requests using:
pip3 install --user lunr==0.5.5
pip3 install --user requests
pip3 install --user pyyaml
pip3 install --user markdown==3.4.1
pip3 install --user pygments==2.13.0The 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-showcaseYou 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/doccodepad- Import CodePad from github.com/defold/codepadrefdoc- Import API reference from latest release at d.defold.comexamples- Import examples from github.com/defold/examplesasset-portal- Import Asset Portal content from github.com/defold/asset-portalgames-showcase- Import Showcase content from github.com/defold/games-showcasesearchindex- Generates the search indexcommit- Commit changes to GitHub (for CI use)
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
- github-pages gem
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 quickest way to install a new Ruby version on macOS/Linux us to use rbenv or ruby. To install it on macOS you first need to install brew:
Open a terminal window and install brew by running the following command:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"brew install rubyAlso add the it to the PATH vaiable in you shell profile (e.g. ~/.zshrc):
export PATH="/opt/homebrew/opt/ruby/bin:$PATH"Open a terminal window and install rbenv by running the following commands:
# use brew to install rbenv
brew install rbenv
# install rbenv shell support every time a shell is started
echo 'eval "$(rbenv init -)"' >> ~/.bash_profileNow close the terminal window. Open a new terminal window and install a new Ruby version (this version corresponds to the one defined in the .ruby-version file of this repository):
# use rbenv to install user local version of ruby 2.7.5
rbenv install --local 2.7.5Open a terminal window and install the required Ruby gems by running the following command:
gem install bundler jekyll github-pagesThis will install the gems defined in the Gemfile (bundler, jekyll, github-pages). You are now ready to launch the site locally.
Launch/serve the site locally using:
As a first step, you need to install dependencies:
bundle install./serve.shOnce the site has been built you can test it by pointing your browser to localhost:4000.
You can use the update.py script to pull in and process content from external sources (docs, asset portal etc)
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.shBy setting the DM_DOC_DIR environment variable, you can load the documentation directory from your local folder:
DM_DOC_DIR=/Users/username/work/doc python update.py docsThe site uses GitHub actions to automatically trigger update.py when an external source/repository has been updated. 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 games-showcase workflow on change.
- 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 based on Lunr.js. The search index is generated using the Python equivalent of Lunr. Version 0.5.5 of lunr.py uses Lunr.js version 2.3.6.
Functionality for searching and marking within a single page using Mark.js.
This site uses the following assets: