Skip to content

Latest commit

 

History

History
184 lines (128 loc) · 7.17 KB

README.md

File metadata and controls

184 lines (128 loc) · 7.17 KB
Raw

defold.github.io

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:

HOW TO UPDATE THE SITE WITH NEW CONTENT

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

Requirements

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.0

Usage

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).

Options

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.

Commands

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
  • searchindex - Generates the search index
  • commit - Commit changes to GitHub (for CI use)

HOW TO TEST THE SITE LOCALLY

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.

Requirements

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

1 Install Ruby

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:

1.1 Install brew (macOS)

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)"

1.2 Install ruby

brew install ruby

Also add the it to the PATH vaiable in you shell profile (e.g. ~/.zshrc):

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

1.3 Install rbenv (deprecated)

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_profile

Now 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.5

2 Install gems

Open a terminal window and install the required Ruby gems by running the following command:

gem install bundler jekyll github-pages

This will install the gems defined in the Gemfile (bundler, jekyll, github-pages). You are now ready to launch the site locally.

Usage

Launch/serve the site locally using:

As a first step, you need to install dependencies:

bundle install
./serve.sh

Once 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)

How to test local reference documentation

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

How to test local documentaion

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 python update.py docs

Automatic site update using GitHub Actions

The 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:

Search

Site search

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.

Page search

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

Credits

This site uses the following assets: