Configuration

System Configuration

The $TEDDY_BASE/config/system.json file contains mandatory system configuration that defines the location of the directories containing the sites and themes respectively, as well as a list of static system assets.

{
    "system": {
        "sites": "./sites", 
        "themes": "./themes", 
        "assets": {
            "dir": "./system/assets", 
            "js": {
                "teddy": [ 
                    "vendors/teddy/config.js", 
                    "vendors/teddy/lang.js", 
                    "vendors/teddy/search.js", 
                    "vendors/teddy/site.js"
                ], 
                "vendors": [
                    "vendors/flexsearch/0.7.43/flexsearch.bundle.min.js"
                ]
            }
        }
    }
}

System Configuration Namespaces

system.sites

• Type: string
• Default: ./sites
• Required: Yes
• Description: The absolute path to the parent directory containing the site(s) managed by Teddy.

system.themes

• Type: string
• Default: ./themes
• Required: Yes
• Description: The absolute path to the parent directory containing the theme(s) managed by Teddy.

system.assets.dir

• Type: string
• Default: ./system/assets
• Required: Yes
• Description: The absolute path to the parent directory containing static system assets.

system.assets.dir.js.teddy

• Type: array[string]
• Default: See above
• Required: Yes
• Description: Paths to static JavaScript system assets bespoke to Teddy, relative to {system.assets.dir}/js.

system.assets.dir.js.vendors

• Type: array[string]
• Default: See above
• Required: Yes
• Description: Paths to static open-source JavaScript system assets developed by third-party vendors, relative to {system.assets.dir}/js.

Site Configuration

Each unique site found in {system.sites} must have a site.json configuration file in the root of the site directory. For example, the site configuration for the demo TravelBook site, found in $TEDDY_BASE/sites/travelbook/site.json, is as follows.

{
    "site": {
        "name": "travelbook", 
        "version": "0.0.1", 
        "languages": {
            "enabled": [
                "en", 
                "ja", 
                "zh-tw"
            ]
        }, 
        "assets": {
            "custom": {
                "images": {
                    "favicon": {
                        "deployToRoot": true, 
                        "ico": "favicon/favicon.ico"
                    }, 
                    "og": {
                        "default": "og/og-default.jpg", 
                        "useCover": true
                    }
                }
            }
        }, 
        "collection": {
            "enabled": true, 
            "pagesDir": "blog", 
            "index": {
                "content": true, 
                "documentStore": {
                    "document": {
                        "id": "id", 
                        "tag": "tags", 
                        "index": [
                            "name", 
                            "description"
                        ], 
                        "store": true
                    }
                }
            }, 
            "media": {
                "extensions": {
                    "allowed": [
                        "gif", 
                        "jpg", 
                        "jpeg", 
                        "mp3", 
                        "mp4", 
                        "pdf", 
                        "png"
                    ]
                }
            }, 
            "taxonomy": {
                "categories": [
                    "africa", 
                    "asia", 
                    "australia", 
                    "europe", 
                    "north-america", 
                    "south-america"
                ]
            }, 
            "pagination": {
                "size": 10
            }, 
            "sort": {
                "key": "date", 
                "order": "desc"
            }, 
            "search": {
                "minQueryLength": 2
            }
        }, 
        "html": {
            "inject": {
                "metadata": true, 
                "systemAssets": true
            }
        }, 
        "web": {
            "local": {
                "domain": "localhost:8080", 
                "http": {
                    "secure": false
                }, 
                "host": "simple-web-server"
            }, 
            "production": {
                "domain": "demo.teddyful.com", 
                "http": {
                    "secure": true
                }, 
                "host": "cloudflare-pages"
            }
        }, 
        "urls": {
            "external": {
                "facebook": "https://www.facebook.com", 
                "github": "https://github.com", 
                "instagram": "https://www.instagram.com", 
                "themefisher": "https://github.com/themefisher/logbook-bootstrap", 
                "twitter": "https://x.com"
            }
        }
    }
}

Site Configuration Namespaces

site.name

• Type: string
• Required: Yes
• Example: travelbook
• Description: The name of the site. This should match the name of the site directory, and must only contain alphanumeric, hyphen and underscore characters. Lowercase site names are recommended.

site.version

• Type: string
• Required: Yes
• Example: 0.0.1
• Description: The site version number, in the format X.Y.Z where X is the major version, Y is the minor version, and Z is the patch version.

site.languages.enabled

• Type: array[string]
• Required: Yes
• Example: ['en']
• Description: An array of language codes representing the languages that are supported by your site, where the first language in this array is considered the default language for your site. It is recommended that ISO 639 language codes are used. For every language code defined in this array, a corresponding language directory containing relevant language-specific metadata must exist in {system.sites}/{site.name}/languages/{language.code}. For example, the demo TravelBook site is available in three languages - English en, Japanese ja and Chinese (Traditional) zh-tw. Consequently, the corresponding language directories may be found in $TEDDY_BASE/sites/travelbook/languages. In each language directory, the following files must exist as a minimum: contributors.json, metadata.json and, if site.collection.enabled is set to true, then taxonomy.json as well.

site.assets.custom.css

• Type: array[string]
• Required: No
• Example: ['style.css']
• Description: An array of custom site-specific static CSS asset file paths, relative to {system.sites}/{site.name}/assets/css. If site.assets.minify.css is set to true, then minified versions of the CSS files specified in this array will automatically be created with .min.css replacing their original .css file extension. For any custom site-specific CSS files that are already minified, then there is no need to include them in this array, and they will still be copied to the public distribution folder when your static site is built (during the build, the {system.sites}/{site.name}/assets/css folder, and hence its entire contents, is copied to the public distribution folder).

site.assets.custom.images.favicon.deployToRoot

• Type: boolean
• Required: No
• Example: true
• Description: If this is set to true, then the site favicon ICO file, the path to which is specified in site.assets.custom.images.favicon.ico, is copied to the root directory of the public distribution folder when your static site is built.

site.assets.custom.images.favicon.ico

• Type: string
• Required: No
• Example: favicon/favicon.ico
• Description: The path to the site favicon ICO file, relative to {system.sites}/{site.name}/assets/images.

site.assets.custom.images.og.default

• Type: string
• Required: No
• Example: og/og-default.jpg
• Description: The path to an image file, relative to {system.sites}/{site.name}/assets/images, that will be used as the default Open Graph protocol image if no Open Graph image is defined in the frontmatter metadata of the page markdown file.

site.assets.custom.images.og.useCover

• Type: boolean
• Required: No
• Example: true
• Description: If this is set to true, and no Open Graph image is defined in the frontmatter metadata of the page markdown file, then the Open Graph image for the page will be set to the page cover image if the cover image is defined in the frontmatter metadata. Note that the cover image, if defined, will take precedence over the default Open Graph image specified in site.assets.custom.images.og.default, if defined.

site.assets.custom.js

• Type: array[string]
• Required: No
• Example: ['main.js']
• Description: An array of custom site-specific static JavaScript asset file paths, relative to {system.sites}/{site.name}/assets/js. If site.assets.minify.js is set to true, then minified versions of the JavaScript files specified in this array will automatically be created with .min.js replacing their original .js file extension. For any custom site-specific JavaScript files that are already minified, then there is no need to include them in this array, and they will still be copied to the public distribution folder when your static site is built (during the build, the {system.sites}/{site.name}/assets/js folder, and hence its entire contents, is copied to the public distribution folder).

site.collection.enabled

• Type: boolean
• Required: Yes
• Example: true
• Description: Set this to true if your site includes a collection of documents to be indexed. For example, sites that include a blog (and hence a collection of blog posts), or sites used for documentation (and hence include a collection of guides) should set this to true. Note that a site may only contain a single collection. When enabled, pages in the collection may be queried using free-text search queries, and filtered using category and tag filters.

site.collection.pagesDir

• Type: string
• Required: If site.collection.enabled is set to true
• Example: blog
• Description: The path to the directory, relative to ${system.sites}/{site.name}/pages, that contains the collection of pages to be indexed.

site.collection.index.content

• Type: boolean
• Required: If site.collection.enabled is set to true
• Example: true
• Description: Set this to true if you wish to index the text content of all pages in the collection. Note that selected page metadata, specifically page name, description, categories and tags, for all pages in the collection are indexed by default. See site.collection.index.documentStore for further details.

site.collection.index.documentStore

• Type: object
• Required: If site.collection.enabled is set to true
• Example: See above
• Description: The configuration object that is used by the third-party open-source Flexsearch full-text search library to initialise a Flexsearch document store. Teddy utilises Flexsearch to create an indexed document store so that the site collection may be queried and filtered. For further information on the FlexSearch API, and to view the full range of initialisation options available, please visit https://github.com/nextapps-de/flexsearch.

site.collection.media.extensions.allowed

• Type: array[string]
• Required: If site.collection.enabled is set to true
• Example: See above
• Description: An array of media file extensions that will determine which page-specific media files, found in ${system.sites}/{site.name}/pages/{...page}/, are copied to the public distribution folder when your static site is built.

site.collection.taxonomy.categories

• Type: array[string]
• Required: If site.collection.enabled is set to true
• Example: See above
• Description: An array of categories. Pages in your collection, if enabled, may belong to zero, one or more categories. The categories that a page belongs to is defined in the frontmatter metadata of that page. During the build, the number of pages, per language, found in each of the categories listed in this array is computed and made available for use by mustache-based theme templates.

site.collection.pagination.size

• Type: integer
• Required: If site.collection.enabled is set to true
• Example: 10
• Description: The limit size when the Flexsearch document store is queried, limiting the number of results returned by a single query to this upper bound.

site.collection.sort.key

• Type: string
• Required: If site.collection.enabled is set to true
• Example: date
• Description: The document property that is used to sort the collection. The document properties that are available, by default, are:
  • author
  • authorUrl
  • cover
  • date
  • description
  • name

site.collection.sort.order

• Type: enum
• Enum Value: asc, desc
• Required: If site.collection.enabled is set to true
• Example: desc
• Description: The sort order to apply to the document property that is used to sort the collection. Only the values asc or desc are allowed.

site.collection.search.minQueryLength

• Type: integer
• Required: If site.collection.enabled is set to true
• Example: 2
• Description: The minimum length, post-sanitisation, of a free-text query string that is required in order to instigate a search of the Flexsearch document store.

site.html.inject.metadata

• Type: boolean
• Required: Yes
• Example: true
• Description: If this is set to true, the following Open Graph protocol metadata tags will automatically be generated and injected into the generated HTML for all pages created as part of the static site:
  • og:description
  • og:image
  • og:site_name
  • og:title
  • og:type
  • og:url

The following metadata tags will also be created for all pages belonging to the specified collection, if enabled:

• article:author
• article:modified_time
• article:section
• article:tag

site.html.inject.systemAssets

• Type: boolean
• Required: Yes
• Example: true
• Description: If this is set to true, all the system-specific static JavaScript assets defined in system.assets.js will automatically be included in the generated HTML for all pages via the HTML <script> tag. It is strongly recommended to set this value to true.

site.web.{env}.domain

• Type: string
• Required: Yes
• Examples:
  • local: localhost:8080
  • production: teddyful.com
• Description: The name of the domain that will be used to access the static site, via HTTP, in the given environment.

site.web.{env}.http.secure

• Type: boolean
• Required: Yes
• Examples:
  • local: false
  • production: true
• Description: Whether access to the static site, in the given environment, is secured via HTTPS.

site.web.{env}.host

• Type: string
• Required: Yes
• Example: cloudflare-pages
• Description: The name of the web host for the given environment. Dependent on the value, the relevant web server configuration file will be copied to the root of the public distribution directory when your static site is built. If this is set to apache-http-server, then the .htaccess web server configuration file found in ${system.sites}/{site.name}/web/hosts/apache will be copied. If this is set to cloudflare-pages, then the _headers Cloudflare Pages configuration file found in ${system.sites}/{site.name}/web/hosts/cloudflare/pages will be copied. For any other values, no action will currently be taken.

site.urls

• Type: object
• Required: Yes
• Example: See above
• Description: An arbitrary object containing URLs, common to the pages of your site, that are made available for use by mustache-based theme templates, markdown-based pages, and JSON-based language files.

Theme Configuration

Each unique theme found in {system.themes} must have a theme.json configuration file in the root of the theme directory. For example, the theme configuration for the default Bear theme, found in $TEDDY_BASE/themes/bear/theme.json, is as follows:

{
    "theme": {
        "name": "bear", 
        "version": "0.0.1", 
        "author": "Jillur Quddus", 
        "repo": "https://github.com/teddyful/teddy", 
        "license": "https://github.com/teddyful/teddy/blob/main/LICENSE", 
        "assets": {
            "custom": {
                "css": [
                    "style.css"
                ], 
                "js": [
                    "blog.js"
                ]
            }
        }
    }
}

Theme Configuration Namespaces

theme.name

• Type: string
• Required: Yes
• Example: bear
• Description: The name of the theme. This should match the name of the theme directory, and must only contain alphanumeric, hyphen and underscore characters. Lowercase theme names are recommended.

theme.version

• Type: string
• Required: Yes
• Example: 0.0.1
• Description: The theme version number, in the format X.Y.Z where X is the major version, Y is the minor version, and Z is the patch version.

theme.author

• Type: string
• Required: Yes
• Example: Jillur Quddus
• Description: The name(s) of the primary author(s) of the theme, comma-delimited if applicable.

theme.repo

• Type: string
• Required: No
• Example: https://github.com/teddyful/teddy-bear
• Description: The URL to the theme version-controlled source code repository, if one exists.

theme.license

• Type: string
• Required: No
• Example: https://github.com/teddyful/teddy-bear/blob/main/LICENSE
• Description: The URL to the theme license file, if one exists.

theme.assets.custom.css

• Type: array[string]
• Required: No
• Example: ['style.css']
• Description: An array of custom theme-specific static CSS asset file paths, relative to {system.themes}/{theme.name}/assets/css. If site.assets.minify.css is set to true, then minified versions of the CSS files specified in this array will automatically be created with .min.css replacing their original .css file extension. For any custom theme-specific CSS files that are already minified, then there is no need to include them in this array, and they will still be copied to the public distribution folder when your static site is built (during the build, the {system.themes}/{theme.name}/assets/css folder, and hence its entire contents, is copied to the public distribution folder).

theme.assets.custom.images.favicon.deployToRoot

• Type: boolean
• Required: No
• Example: true
• Description: If this is set to true, then the theme favicon ICO file, the path to which is specified in theme.assets.custom.images.favicon.ico, is copied to the root directory of the public distribution folder when your static site is built.

theme.assets.custom.images.favicon.ico

• Type: string
• Required: No
• Example: favicon/favicon.ico
• Description: The path to the theme favicon ICO file, relative to {system.themes}/{theme.name}/assets/images. Note that, if defined, the site-specific favicon ICO file specified in site.assets.custom.images.favicon.ico will take precedence over the theme-specific favicon ICO file.

theme.assets.custom.images.og.default

• Type: string
• Required: No
• Example: og/og-default.jpg
• Description: The path to an image file, relative to {system.themes}/{theme.name}/assets/images, that will be used as the default Open Graph protocol image if no Open Graph image is defined in the frontmatter metadata of the page markdown file. Note that, if defined, the site-specific default Open Graph image file specified in site.assets.custom.images.og.default will take precedence over the theme-specific default Open Graph image file.

theme.assets.custom.images.og.useCover

• Type: boolean
• Required: No
• Example: true
• Description: If this is set to true, and no Open Graph image is defined in the frontmatter metadata of the page markdown file, then the Open Graph image for the page will be set to the page cover image if the cover image is defined in the frontmatter metadata. Note that the cover image, if defined, will take precedence over the default Open Graph image specified in theme.assets.custom.images.og.default, if defined.

theme.assets.custom.js

• Type: array[string]
• Required: No
• Example: ['blog.js']
• Description: An array of custom theme-specific static JavaScript asset file paths, relative to {system.themes}/{theme.name}/assets/js. If site.assets.minify.js is set to true, then minified versions of the JavaScript files specified in this array will automatically be created with .min.js replacing their original .js file extension. For any custom theme-specific JavaScript files that are already minified, then there is no need to include them in this array, and they will still be copied to the public distribution folder when your static site is built (during the build, the {system.themes}/{theme.name}/assets/css folder, and hence its entire contents, is copied to the public distribution folder).