Build

Version: Latest • 1 March 2025

Static site build command and available build options

Build Pipeline

The build is an ordered series of tasks, aggregated into a single pipeline, that creates a static site ready for deployment. The end-to-end build pipeline is illustrated in the following diagram.

Static site build pipeline

The high-level stages of this build pipeline are as follows.

  1. The content of each language-specific markdown-based page contained within a site is converted into HTML. The markdown frontmatter containing the page metadata is also extracted and parsed.
  2. The converted page content HTML and metadata, along with the localised site metadata, is injected into relevant HTML templates belonging to the specified theme.
  3. The resultant localised HTML files, representing each of the pages contained within the site, are written to the static site distribution directory.
  4. A configurable subset of the pages, called a collection, is indexed and loaded into an efficient and flat file-based document store database. The document store is then written to the static site distribution directory to enable the static site to provide free-text search and filtering capabilities.
  5. Site-specific static assets, including CSS, JavaScript, font and image files, are copied to a dedicated assets folder in the static site distribution directory.
  6. Theme-specific static assets, including CSS, JavaScript, font and image files, are also copied to the same dedicated assets folder in the static site distribution directory.
  7. Finally, site-specific web configuration files, including robots.txt, sitemaps and target deployment environment & platform-specific configuration files (for example .htaccess for Apache HTTP Server, or _headers for Cloudflare Pages) are also copied to the static site distribution directory.

The static site is then ready to be deployed to the environment or platform of your choice, for example a shared web hosting service, public cloud environment, or a JAMstack platform such as Cloudflare Pages.

Build Command

To build your static site locally, open your command line application (Command Prompt in Windows or the Terminal in Linux), navigate to $TEDDY_BASE and execute the following command, replacing {site.name} with the name of the site in $TEDDY_BASE/sites that you wish to build, and {theme.name} with the name of the theme in $TEDDY_BASE/themes that you wish to use. Note that this command will only build the static site. It will not deploy it to the internet.

npm run build -- --site-name {site.name} --theme-name {theme.name}

For example, the following command is used to build the demo TravelBook site using the default Bear template.

npm run build -- --site-name travelbook --theme-name bear

           _     _
          ( \---/ )
           ) . . (
 ____,--._(___Y___)_,--.____
     `--'           `--'
            TEDDY
         teddyful.com
 ___________________________


2025-03-17 11:47:04.105 [Teddy] INFO: Started the Teddy static website builder (v0.0.2).
2025-03-17 11:47:04.106 [Teddy] INFO: Building the static site...
2025-03-17 11:47:04.107 [Teddy] INFO: Site name: travelbook
2025-03-17 11:47:04.107 [Teddy] INFO: Theme name: bear
2025-03-17 11:47:04.107 [Teddy] INFO: Environment name: local
2025-03-17 11:47:04.107 [Teddy] INFO: Stage 1 of 12 - Validating configuration...
2025-03-17 11:47:04.151 [Teddy] INFO: Stage 2 of 12 - Aggregating configuration...
2025-03-17 11:47:04.281 [Teddy] INFO: Stage 3 of 12 - Pre-build cleaning...
2025-03-17 11:47:04.329 [Teddy] INFO: Stage 4 of 12 - Setting up the build environment...
2025-03-17 11:47:04.330 [Teddy] INFO: Stage 5 of 12 - Deploying static artifacts...
2025-03-17 11:47:04.336 [Teddy] INFO: Stage 6 of 12 - Indexing the collection...
2025-03-17 11:47:05.427 [Teddy] INFO: Stage 7 of 12 - Building templates...
2025-03-17 11:47:05.532 [Teddy] INFO: Stage 8 of 12 - Building pages...
2025-03-17 11:47:05.948 [Teddy] INFO: Stage 9 of 12 - Building custom assets...
2025-03-17 11:47:05.949 [Teddy] INFO: Stage 10 of 12 - Building system assets...
2025-03-17 11:47:05.951 [Teddy] INFO: Stage 11 of 12 - Deploying assets...
2025-03-17 11:47:05.952 [Teddy] INFO: Stage 12 of 12 - Post-build cleaning...
2025-03-17 11:47:05.953 [Teddy] INFO: Successfully finished building the static site!
2025-03-17 11:47:05.953 [Teddy] INFO: Build directory: ./sites/travelbook/public/local
2025-03-17 11:47:05.954 [Teddy] INFO: Build duration: 1847.236ms
2025-03-17 11:47:05.954 [Teddy] INFO: Exiting the Teddy static website builder (exitCode = 0).

Site Output

The static site will be built in $TEDDY_BASE/sites/{site.name}/public/{env}, hereafter referred to as the public distribution directory, where site.name is the name of the site, for example travelbook, and env is the environment name that is set to local by default if not provided as a command line argument. All system-specific, site-specific and theme-specific static assets, including CSS, JavaScript, font and image files, will be copied to $TEDDY_BASE/sites/{site.name}/public/{env}/assets/{site.version} by default, where site.version is the site version number.

Command Line Arguments

The following command line arguments should be provided when running the command to build your static site. --site-name and --theme-name are mandatory, and --env is optional but recommended.

--site-name {site.name}

  • Required: Yes
  • Default Value: No default value
  • Example: --site-name travelbook
  • Description: The name of the site, that must exist in $TEDDY_BASE/sites, that you wish to build.

--theme-name {theme.name}

  • Required: Yes
  • Default Value: No default value
  • Example: --theme-name bear
  • Description: The name of the theme, that must exist in $TEDDY_BASE/themes, that you wish to use.

--env {env}

  • Required: No
  • Default Value: local
  • Examples: --env local, --env test, --env qa, --env pre-production, --env production
  • Description: The name of the build environment. The static site will be built in $TEDDY_BASE/sites/{site.name}/public/{env} where env is the environment name, which is set to local by default if this command line argument is not provided. The environment name, if provided, must only contain alphanumeric, hyphen and underscore characters. Lowercase environment names are recommended. Note that a configuration object with exactly the same name as the environment must be configured in the site.web namespace of the site configuration site.json file for the specified site, otherwise a validation error will be thrown when building your static site. Please refer to the site configuration guide for further details.

Example Build with Environment Name

The following command is used to build the demo TravelBook site using the default Bear template in a production environment.

npm run build -- --site-name travelbook --theme-name bear --env production

Using this example, the static site will be created in $TEDDY_BASE/sites/travelbook/public/production.

Build Options

The following build options are also available when running the command to build your static site, and may be optionally provided as additional command line arguments.

--custom-css-only

If this build option is provided, only custom site-specific static CSS assets defined in the site.assets.custom.css namespace of the site configuration, and custom theme-specific static CSS assets defined in the theme.assets.custom.css namespace of the theme configuration, will be copied to the public distribution directory when your static site is built. All other static CSS assets will be ignored.

--custom-js-only

If this build option is provided, only custom site-specific static JavaScript assets defined in the site.assets.custom.js namespace of the site configuration, and custom theme-specific static JavaScript assets defined in the theme.assets.custom.js namespace of the theme configuration, will be copied to the public distribution directory when your static site is built. All other static JavaScript assets will be ignored.

--dist-use-build-id

When the build command is run, your static site will be created in $TEDDY_BASE/sites/{site.name}/public/{env} as described previously. By default, all static assets will be copied into $TEDDY_BASE/sites/{site.name}/public/{env}/assets/{site.version} where site.version is the site version number defined in the site configuration. By providing this --dist-use-build-id build option, the build ID will be used instead of the site version number. Consequently, all static assets will be copied into $TEDDY_BASE/sites/{site.name}/public/{env}/assets/{build.id}, where build.id is of the format {site.version}-{build.date}, and where build.date is of the format YYYYMMDDHHmmss in the UTC timezone. An example build ID is: 0.0.1-20250301121314.

--ignore-assets

If this build option is provided, no static assets will be copied to the public distribution assets directory when your static site is built. Consequently, all site-specific and theme-specific static CSS, JavaScript, font and image assets will be ignored. This build option is useful in the scenario where you have previously built your static site without providing this build option, but thereafter only wish to propagate page content updates without having to re-copy across unchanged static assets during each build. When this build option is provided, the assets directory $TEDDY_BASE/sites/{site.name}/public/{env}/assets/, if previously built, will not be cleared and will remain unchanged.

--ignore-collection

If this build option is provided, the collection of pages, configured in the site.collection namespace of the site configuration, will not be indexed.

--ignore-css

If this build option is provided, no static CSS assets will be copied to the public distribution assets directory when your static site is built. Consequently, all site-specific and theme-specific static CSS files will be ignored.

--ignore-fonts

If this build option is provided, no static font assets will be copied to the public distribution assets directory when your static site is built. Consequently, all site-specific and theme-specific static font files will be ignored.

--ignore-html

If this build option is provided, no HTML files corresponding to any of your markdown-based pages will be generated.

--ignore-images

If this build option is provided, no static image assets will be copied to the public distribution assets directory when your static site is built. Consequently, all site-specific and theme-specific static image files will be ignored.

--ignore-js

If this build option is provided, no static JavaScript assets will be copied to the public distribution assets directory when your static site is built. Consequently, all site-specific and theme-specific static JavaScript files will be ignored.

--ignore-robots

If this build option is provided, the robots.txt website configuration file, found in $TEDDY_BASE/sites/{site.name}/web/robots/robots.txt, will not be copied to root of the public distribution directory when your static site is built.

--ignore-sitemap

If this build option is provided, the sitemap.xml website configuration file, found in $TEDDY_BASE/sites/{site.name}/web/sitemap/sitemap.xml, will not be copied to root of the public distribution directory when your static site is built.

--ignore-web-config

If this build option is provided, the web server configuration file(s), found in $TEDDY_BASE/sites/{site.name}/web/hosts/, pertaining to the host specified in the site.web namespace of the site configuration, will not be copied to root of the public distribution directory when your static site is built.

--minify-css

If this build option is provided, minified versions of all custom site-specific static CSS assets defined in the site.assets.custom.css namespace of the site configuration, and custom theme-specific static CSS assets defined in the theme.assets.custom.css namespace of the theme configuration, will be created in the public distribution assets directory when your static site is built.

--minify-html

If this build option is provided, all HTML files corresponding to all of your markdown-based pages will be minified when generated.

--minify-js

If this build option is provided, minified versions of all custom site-specific static JavaScript assets defined in the site.assets.custom.js namespace of the site configuration, and custom theme-specific static JavaScript assets defined in the theme.assets.custom.js namespace of the theme configuration, will be created in the public distribution assets directory when your static site is built.

--skip-post-build-cleanup

The last task performed by the build pipeline is to delete all temporary build resources created in $TEDDY_BASE/sites/{site.name}/build/{env}/{site.version}. These temporary resources include the full and aggregated system, site and theme JSON configuration, language-specific aggregated metadata, and language-specific theme templates. If this build option is provided, all temporary build resources are preserved.

Example with Build Options

The following command is used to build the demo TravelBook site (version 0.0.1) using the default Bear template in a local development environment whilst preserving all temporary build resources.

npm run build -- --site-name travelbook --theme-name bear --env local --skip-post-build-cleanup

           _     _
          ( \---/ )
           ) . . (
 ____,--._(___Y___)_,--.____
     `--'           `--'
            TEDDY
         teddyful.com
 ___________________________


2025-03-17 11:47:39.004 [Teddy] INFO: Started the Teddy static website builder (v0.0.2).
2025-03-17 11:47:39.006 [Teddy] INFO: Building the static site...
2025-03-17 11:47:39.006 [Teddy] INFO: Site name: travelbook
2025-03-17 11:47:39.006 [Teddy] INFO: Theme name: bear
2025-03-17 11:47:39.006 [Teddy] INFO: Environment name: local
2025-03-17 11:47:39.006 [Teddy] INFO: Stage 1 of 12 - Validating configuration...
2025-03-17 11:47:39.050 [Teddy] INFO: Stage 2 of 12 - Aggregating configuration...
2025-03-17 11:47:39.171 [Teddy] INFO: Stage 3 of 12 - Pre-build cleaning...
2025-03-17 11:47:39.222 [Teddy] INFO: Stage 4 of 12 - Setting up the build environment...
2025-03-17 11:47:39.224 [Teddy] INFO: Stage 5 of 12 - Deploying static artifacts...
2025-03-17 11:47:39.229 [Teddy] INFO: Stage 6 of 12 - Indexing the collection...
2025-03-17 11:47:40.391 [Teddy] INFO: Stage 7 of 12 - Building templates...
2025-03-17 11:47:40.489 [Teddy] INFO: Stage 8 of 12 - Building pages...
2025-03-17 11:47:40.908 [Teddy] INFO: Stage 9 of 12 - Building custom assets...
2025-03-17 11:47:40.909 [Teddy] INFO: Stage 10 of 12 - Building system assets...
2025-03-17 11:47:40.911 [Teddy] INFO: Stage 11 of 12 - Deploying assets...
2025-03-17 11:47:40.912 [Teddy] INFO: Stage 12 of 12 - Post-build cleaning...
2025-03-17 11:47:40.912 [Teddy] INFO: Successfully finished building the static site!
2025-03-17 11:47:40.913 [Teddy] INFO: Build directory: ./sites/travelbook/public/local
2025-03-17 11:47:40.913 [Teddy] INFO: Build duration: 1907.600ms
2025-03-17 11:47:40.914 [Teddy] INFO: Exiting the Teddy static website builder (exitCode = 0).

Using this example, the static site will be created in $TEDDY_BASE/sites/travelbook/public/local/, system-specific, site-specific and theme-specific static assets will be copied to $TEDDY_BASE/sites/travelbook/public/local/assets/0.0.1/, and temporary build resources may be found in $TEDDY_BASE/sites/travelbook/build/local/0.0.1/. The site directory structure will thereafter be as follows (non-exhaustive).

$TEDDY_BASE/
├── config/
│   └── system.json
├── sites/
│   └── travelbook/
│       └── assets/
│       └── build/                          <-- temporary build resources
│           └── local/
│               └── 0.0.1/
│                   └── config/
│                       └── config.json     <-- aggregated configuration
│                   └── languages/          <-- language-specific aggregated metadata
│                       └── en.json
│                       └── ja.json
│                       └── zh-tw.json
│                   └── templates/          <-- language-specific templates
│                       └── en/
│                           └── about.html
│                           └── blog.html
│                           └── page.html
│                           └── post.html
│                       └── ja/
│                           └── about.html
│                           └── blog.html
│                           └── page.html
│                           └── post.html
│                       └── zh-tw/
│                           └── about.html
│                           └── blog.html
│                           └── page.html
│                           └── post.html
│       └── languages/
│       └── pages/
│       └── public/                         <-- static site
│           └── assets/                     <-- static site aggregated assets
│               └── 0.0.1/
│                   └── collection/         <-- indexed collection
│                   └── css/                <-- aggregated CSS assets
│                   └── fonts/              <-- aggregated font assets
│                   └── images/             <-- aggregated image assets
│                   └── js/                 <-- aggregated JavaScript assets
│           └── build.json
│           └── favicon.ico
│           └── index.html
│           └── robots.txt
│           └── sitemap.xml
│       └── web/
│       └── site.json
├── system/
├── themes/
├── build.js
├── package.json

Build Logs

Detailed log files are generated when the build command is executed, including low-level debug logging and stack traces related to any build errors that may occur. These log files may be found in $TEDDY_BASE/logs and are rotated on a daily basis, with the last 31 days of log files preserved by default. Please consult these log files to troubleshoot any build errors, or if you simply wish to understand the build pipeline in further detail.

©  HyperLearning AI. All rights reserved.

Contents