Configuration File

As you have possibly already learnt, a Bestatic site can be configured using a bestatic.yaml file (previously named config.yaml, which still works but is deprecated). You can probably change anything and everything about your website and blog using this config file. You cannot rename it to anything else; you cannot put it anywhere other than the root directory of your site; also, toml/json/etc. cannot be used here.

A sample bestatic.yaml file is first provided below. This file demonstrates most of the available configuration options in v0.0.36.

Sample config file (with comments)

siteURL: "https://example.org"  # Replace with the URL of your site; Please do not add a trailing slash
title: "A Great Site | With a Tagline"  # Title of your website
description: "Something to describe your website in brief."  # Short description of your website for metadata

theme: Modular # Enter the theme you want to use for your site; make sure the same theme is present in the 'themes' directory

number_of_pages: 2 # Enter the number of blog pages to paginate blog posts

summary_length: 500 # Enter the character length of the summary you want to display on the Blog listing pages. The default is 250 characters.

# Navigation - can be nested as required. Themes can use this to build navigation menus automatically. 
nav:
  - Home: /
  - User Guide:
      - Writing your docs: /writing-your-docs
      - Styling your docs: /styles/styling-your-docs
      - Customizing your docs: /customizing-your-docs
      - Blog:
          - Blogging with Bestatic: /blogging-with-bestatic
          - Advanced:
              - Blogging with Markdown: /blogging-with-markdown
              - Custom Styling: /custom-styling
              - Templates: /templates
  - About:
      - License: /legal/license
      - Release Notes: /release-notes


# Post/Blog configuration
post_directory: 
  singular: blog    # URL prefix for individual posts. Default is 'post'. 
  plural: blog      # URL path for post listings. Default is 'posts'.

# Taxonomies - define custom taxonomies with templates and directories

taxonomies:
  tags:
    taxonomy_template: taglist.html.jinja2
    taxonomy_directory: tags
  categories:  # Example of additional taxonomy
    taxonomy_template: category.html.jinja2
    taxonomy_directory: categories
  authors:     # Example of additional taxonomy
    taxonomy_template: author.html.jinja2
    taxonomy_directory: authors

# Date and time configuration
time_format: "%B %d %Y"  # Enter the time format you want to display on your site; use the format of strftime (https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes and https://strftime.org/ for reference)
timezone: "America/New_York"  # Timezone for date/time processing, defaults to UTC if not specified


enable_inject_tag: true

include_post_in_pages: true  # Allow page-type content to access post data

# Homepage configuration
homepage_type: default  # Options: "default" or "list"

# Shortcodes configuration
SHORTCODES: true  # Enable custom shortcodes support. For more info on shortcodes, see the documentation.

# Markdown configuration. You can add custom extensions and configs here as well (you have to install python-markdown packages via PIP unless you are using the included extensions).

markdown:
  markdown_replace: false # Set to true to replace the default extensions with your own custom extensions. 
  extensions: 
    - md_in_html
    - toc
    - markdown_include.include
  extension_configs:
    markdown_include.include:
      base_path: ./_includes   # Base path for markdown-include extension. Here you should store your files that you call from another markdown file. You can have folder named _includes as well.
    toc:
      marker: "[My Table of Contents]"
    # codehilite:
    #   linenos: table

# Comments configuration
comments:
  enabled: true # Set to false to disable comments
  system: giscus  # Enter "disqus" or "giscus" here
  comment_system_id: "username/repo"

# RSS feed
rss_feed: true # Set to false to disable RSS feed generation. If you have posts, it is generated by default.

# Image processing configuration (New in v0.0.36)
image_processing:
  enabled: true              # Enable automatic image optimization and WebP conversion
  quality: 80                # WebP quality (1-100, default: 80)
  keep_original: false       # Keep original images alongside WebP versions
  include_formats:           # Image formats to process

extra_data: # This is a new section introduced in v0.0.36. You can use this to add additional data to your website and blog. For example, you can add a second (or more) navigation menu to your website. You have to use the key extra_data and then the key you want to use for your additional data.
  - second_nav:
    - Welcome: /docs
    - Quickstart: /docs/quickstart
    - Installation:
      - Overview: /docs/installation 
      - Windows: /docs/installation#windows
      - Linux: /docs/installation#linux
      - macOS: /docs/installation#macos
  - docs_nav:
    - Overview:
      - Title: Bestatic Documentation
      - Summary: <p>Bestatic is a minimal yet fully-featured static site generator built with Python and Jinja2 template engine.</p><p>Please browse through the pages listed below to get started and to explore in-depth. If you have any questions, please feel free to contact me on <a href="https://github.com/tatsatb/bestatic/discussions">GitHub Discussions</a>.</p>
    - Quickstart: 
      - Link: /docs/quickstart
      - Description: Qucikly learn how to build a site with Bestatic, without delving into nitty-gritty technical details.
    - Installation:
      - Link: /docs/installation
      - Description: Learn how to install Bestatic in different platforms such as Windows, Linux, and macOS (and in development mode with a virtual environment).

Detailed notes on config file

Note that, as this is a yaml file, indentation is very important. Order of fields is not important, but the indentation is.

siteURL: Provide full base URL of your site; it can be https://example.org or https://example.github.io or https://example.netlify.app. Do NOT add a trailing slash. This siteURL parameter is important - Bestatic uses it to generate sitemap (sitemap.xml file; helpful for search engines to crawl your site), RSS feed (index.rss file), and search index (index.json file).
title: Necessary field. As you should understand, you need to have a title for your website! This will go into site's metadata. If you have used bestatic quickstart, you had to input it on command line. You can always change it here (you have to surround with double quotation mark) and rebuild the site.
description: Necessary field. As you should understand, you need to have a short description for your website! This will also go into site's metadata. If you have used bestatic quickstart, you had to input it on command line. You can always change it here (you have to surround it with double quotation mark) and rebuild the site.
theme: Specify your theme name. This is also a necessary field (default theme value is "Amazing"). Bestatic cannot build your website properly (or at all) if a proper theme is not present at the themes folder. You can change the name of the active theme here or you can supply it with -t (or --theme) flag while building the website for the first time. For example, bestatic quickstart -t Modular will try to build website with "Modular" theme. You can download the themes from the GitHub theme repo, themes page, or simply create your own Bestatic theme.
number_of_pages: Specify the number of list pages for your blog. You can skip this if your website does not have blog posts and contains only static pages.
summary_length: (New in v0.0.30) Define the character length of post summaries displayed on list pages. This allows you to control how much preview text is shown for each post on the main list page. The default is 250 characters.
nav: (New in v0.0.30) Define your site's navigation structure directly in the configuration file. Navigation can be nested as deeply as required and as supported by your theme (as shown in the example above). Each item can be a simple key-value pair (e.g., Home: /) or a nested structure for dropdown menus (see example above). External links (starting with http:// or https://) and internal links are both supported. Compatible themes will automatically render this navigation without requiring template editing. Themes can also choose to ignore it and use their own hardcoded navigation structure if desired.
post_directory: singular and post_directory: plural: (New in v0.0.30) Customize the URL parameter for your blog posts. By default, posts are served at /post and listed at /posts. You can change these to "blog"/"blogs", "news"/"news", "articles"/"article", etc. This makes your URL structure more meaningful for your specific use case.
taxonomies: (New in v0.0.30) Define custom taxonomies for organizing your content beyond the default "tags". Each taxonomy is defined as a dictionary with two properties: taxonomy_template (the Jinja2 template to use for rendering taxonomy pages) and taxonomy_directory (the URL directory for that taxonomy). For example, you can add "categories", "authors", or any other classification system. Each taxonomy will generate its own list pages. You can also provide additional YAML data for each taxonomy term (e.g., author biographies) by placing YAML files in the _includes/yamls/ directory. See the content management section on custom taxonomies and the yaml data handling section on taxonomy data files for more details on how to use taxonomies in your website and blog.
date_format: (New in v0.0.30) Customize how dates are displayed using Python's strftime format codes here and here. The default fallback is "%B %d, %Y" (e.g., "December 22, 2025"). You can use formats like "%Y-%m-%d", "%d/%m/%Y", or any other strftime-compatible format.
timezone: (New in v0.0.30) Set the timezone for date/time processing. Default is "UTC". Use standard tz database timezone names like "America/New_York", "Europe/London", "Asia/Tokyo", etc.
include_post_in_pages: (New in v0.0.30) When set to true, page-type content can access all post-type content data. This enables you to create custom post listings or archives on any static non-blog pages (for example, if you want to show the title and summary of recent blog posts on the home page, you can set this to true). Default is false.
homepage_type: You can set the value to "default" or "list". The default value is "default". If you have just a blog (like Wordpress/Blogger style blog), you may want your homepage to be a list of blog posts - set homepage_type: list. To set a specific static page as homepage, keep the value to default and follow the instruction provided here. (New in v0.0.30) You can now use a single post as your homepage by setting homepage_type: single_post and specifying the post path in single_post_homepage.
SHORTCODES: (New in v0.0.30) Set to true to enable custom shortcodes support. When enabled, Bestatic will look for Python files in the _shortcodes directory at your site root and make them available for use in your markdown content. For more details on shortcodes, see the shortcodes section.
markdown.extensions: (New in v0.0.30) Add custom Python-Markdown extensions beyond the default set. Extensions are specified under the markdown section with an extensions list. Common extensions include md_in_html, toc (table of contents), markdown_include.include (for including other markdown files), and many others. For more details on markdown extensions, see the markdown processing section.
markdown.extension_configs: (New in v0.0.30) Configure individual markdown extensions with custom settings under the extension_configs section within markdown. Each extension can have its own configuration block. For example, you can set the base_path for markdown_include.include, customize the TOC marker, or configure code highlighting options like codehilite.linenos. For more details on markdown extension configurations, see the markdown processing section.
comments: You can use this to specify the comment system in your blog. Support for Disqus and Giscus are available by default, as mentioned before.

To enable comments, under comments section of bestatic.yaml, put enabled: true (You can also put enabled: false or delete the comments section altogether, if you prefer not to have comments in your blog, or prefer some other commenting system). Next, mention system: giscus or system: disqus and put comment_system_id: "GitHubUsername/repo" or comment_system_id: "DisqusShortName" accordingly there to enable commenting on your blog.
rss_feed: You can set the value to "true" or "false", depending on whether you want Bestatic to generate an RSS feed for your blog. By default, if you have a blog, Bestatic generates RSS feed (served at siteURL/index.rss). To disable this, you should have rss_feed: false in your bestatic.yaml file.
enable_inject_tag: This injects the meta name="generator" content="Bestatic" tag in the head section of your homepage (if not already provided by your theme). Default value is true and we request you to keep that.
image_processing: (New in v0.0.36) Configure automatic image optimization and WebP conversion. When enabled, Bestatic will automatically convert JPEG, PNG, and GIF images to WebP format, significantly reducing file sizes and improving website performance. See the image optimization documentation for detailed information.
- enabled: Set to true to enable image processing. Default is false. If you do not use this key, image processing will be disabled.
- quality: WebP compression quality from 1-100. Default is 80.
- keep_original: Set to true to keep original images alongside WebP versions. Default is false.
- include_formats: List of image extensions to process. Default is ['.jpg', '.jpeg', '.png', '.gif'].
extra_data: (New in v0.0.36) You can use this to add additional/miscelleneous data to your website and blog. For example, you can add a second (or more) navigation menu to your website. You have to use the key extra_data and then the key you want to use for your additional data. You can use as many nested keys as you want. You can technically add any number of additional data blocks here and Bestatic will now pass it properly to the templates. You can access this data in your templates using the {{ extra_data.key.subkey }} syntax.