Installation

Prerequisites

1. Install Node.js (LTS). Teddy is written in JavaScript and requires the Node.js JavaScript runtime environment to build static sites. It is recommended to install the latest LTS (Long Term Support) version of Node.js.
2. Install Simple Web Server. It is recommended that a local web server is installed to serve, view and test the static website created by Teddy for local development purposes only. We recommend Simple Web Server for its simplicity, however any modern web server, for example Apache Web Server, nginx or using the built-in Node.js HTTP module, will suffice.

Download

Download the latest version of Teddy from Teddy's GitHub releases page, and extract the contents of the archive file into a folder of your choice. The location of this folder will hereafter be referred to as $TEDDY_BASE.

Directory Structure

The directory structure within $TEDDY_BASE is as follows.

$TEDDY_BASE/
├── config/
│   └── system.json
├── sites/
│   └── travelbook/
│       └── assets/
│       └── languages/
│       └── pages/
│       └── web/
│       └── site.json
├── system/
├── themes/
│   └── bear/
│       └── assets/
│       └── templates/
│       └── theme.json
├── build.js
├── package.json

When you instruct Teddy to build your specified site, two additional directories named build and public are created in $TEDDY_BASE/sites/{site.name}. For example, if you build the demo travelbook site by running the command npm run build -- --site-name travelbook --theme-name bear then the directory structure will be updated as follows.

$TEDDY_BASE/
├── config/
│   └── system.json
├── sites/
│   └── travelbook/
│       └── assets/
│       └── build/      <-- created when building travelbook
│       └── languages/
│       └── pages/
│       └── public/     <-- created when building travelbook
│       └── web/
│       └── site.json
├── system/
├── themes/
│   └── bear/
│       └── assets/
│       └── templates/
│       └── theme.json
├── build.js
├── package.json

Directories

Below is a description of each of the directories found within $TEDDY_BASE.

config

The config directory contains system configuration that defines the location of the directories containing the sites and themes respectively, as well as a list of static system assets. For most users there is no need to update the system configuration. Please refer to configuration for further details.

sites

The sites directory contains the content for your sites. Each unique site is self-contained within its own child directory, for example travelbook which contains the content for the demo site. The name of the site, and hence the name of the child directory, must only contain alphanumeric, hyphen and underscore characters. Within each site directory must be a site.json file that defines the configuration for that site. Please refer to configuration for further details regarding site configuration, and refer to the sites guide for further details regarding the required structure of sites.

sites/{site.name}/build

When you instruct Teddy to build your specified site, temporary files such as aggregated configuration files and internationalised theme templates are created in sites/{site.name}/build/{env}/{site.version}. By default, the contents of this directory are deleted at the end of each build.

sites/{site.name}/public

When you instruct Teddy to build your specified site, the static site is created in sites/{site.name}/public/{env}. Whether configuring a local web server for local development purposes, or configuring a JAMstack platform such as Cloudflare Pages when deploying your static site to the internet, sites/{site.name}/public/{env} is the directory that you define in your configuration to serve your static site.

system

The system directory contains the JavaScript source code that is used to validate the system, site and theme configuration, and to build your static site. It also contains the static system assets that are listed in the system configuration, relative to system/assets.

themes

The themes directory contains the themes for your sites. Each unique theme is self-contained within its own child directory, for example bear which contains the static assets and templates for the default theme used by Teddy. The name of the theme, and hence the name of the child directory, must only contain alphanumeric, hyphen and underscore characters. Within each theme directory must be a theme.json file that defines the configuration for that theme. Please refer to configuration for further details regarding theme configuration, and refer to themes for further details regarding the required structure of themes.

build.js

The build.js file is the Command Line Interface (CLI)-based entry point used to run the static site builder.

package.json

The package.json file contains, amongst other build metadata, the current version of Teddy, especially useful before and after performing a system update to confirm the version of Teddy you are using. Please refer to releases for Teddy release notes.

Setup

Open your command line application (Command Prompt in Windows or the Terminal in Linux), navigate to $TEDDY_BASE and execute the following command to download the JavaScript package dependencies that Teddy requires to build static sites. Note that this command only needs to be run once when downloading Teddy, or a new version of Teddy, from its GitHub releases page for the first time. If you wish to upgrade an existing instance of Teddy to the latest version, then using Teddy's out-of-the-box upgrader app will automatically run the following command.

npm install

Local Web Server

To view your static website for local development purposes, configure a locally installed web server to serve the files found in $TEDDY_BASE/sites/{site.name}/public/{env}. For local development purposes only, we recommend using Simple Web Server.

1. Open Simple Web Server.
2. Select 'New Server'.
3. In 'Folder path' navigate to and select $TEDDY_BASE/sites/{site.name}/public/{env} (for example $TEDDY_BASE/sites/travelbook/public/local).
4. Select a port number (8080 by default).
5. Under 'Basic Options', check the 'Automatically show index.html' option.
6. Select 'Create Server'.
7. Run the newly created server.

In your internet browser, navigate to http://localhost:8080 to view your static website.

Next Steps

Read the configuration guide for detailed instructions on how to correctly configure the Teddy system, sites and themes. And read the build guide for detailed instructions on how to build your static site, including a description of the relevant command line arguments and available build options.