config.toml
###############################################################################
##
## Global, site-wide configuration settings
##
###############################################################################
# A friendly name for the generated site.
#
# This is accessible in all templates.
#site_name = ""
# The URL where this generated site is hosted.
#
# This is accessible in all templates.
#site_url = ""
# A description of the generated site.
#
# This is accessible in all templates.
#site_description = ""
# URL where the repositories can be cloned from.
#
# Use the "%REPO%" variable to substitute the repository name.
#
# This can also be set per-repository.
#clone_url = "https://github.com/your_user/%REPO%"
# Which branch to use for generating history.
#
# Itsy-Gitsy currently only supports traversing the history of a single branch,
# which is the one named here. Common options are "master" and "main".
# Defaults to "master" if not specified.
#
# Note that this probably should not contain any remote prefix, like "origin/",
# though it may. Also note that the "default branch" is only a concept for
# remote repositories; local repositories do not have the concept, hence this
# must be explicitly specified.
#
# This can also be set per-repository.
#branch = "master"
# List of directories, each of which contains Git repositories to
# index.
#
# For each directory listed here, Itsy-Gitsy imports all of the
# immediate subdirectories as repositories. Each repository is
# imported with its name set to the name of the subdirectory it is in.
#
# Every repository imported in this way has the global setting from
# this file applied. It is not possible to apply per-repository
# settings for bulk-imported repositories. Repositories that require
# specific configuration can be explicitly specified later in this
# file.
#recursive_repo_dirs = []
# List of files potentially containing repository documentation.
#
# Each repository root is searched for these files, in order. The
# first matching file is provided to the templates as a `readme`
# variable, with the file contents. Markdown files are rendered as
# HTML if the feature is enabled.
#
# This can also be set per-repository.
readme_files = ["README.md", "README"]
# List of files to copy to the site's `global_assets` directory.
#
# The files in this list are copied unmodified, and with the same name, to the
# configured `global_asset` output directory. Use for including global,
# site-wide resources, such as stylesheets, images, and icons.
#
# Currently does NOT support globbing or directories. Each file must be listed
# individually.
#
# Use "%TEMPLATE%" variable to substitute the path to the current
# template folder.
#
# Use "%REPO%" variable to substitute the path to the currently
# processing repository (only sensible when used as a per-repo
# configuration).
#
# This can also be set per-repository, in which case the `repo_assets` output
# directory is used.
asset_files = ["%TEMPLATE%/style.css"]
# Whether to split history output into pages
#
# If non-zero and a `history` template is specified, the history
# output is generated several times, each with the `history` variable
# in the template engine containing the next `paginate_history` number
# of entries.
#
# A `page` variable is available in the template, which contains the
# current, next, previous, and total number of pages.
#
# Use the "%PAGE%" variable in the `history` output variable to
# substitute the page number into the produced filename.
paginate_history = 50
# Whether to split branches output into pages
#
# If non-zero and a `branches` template is specified, the branches
# output is generated several times, each with the `branches` variable
# in the template engine containing the next `paginate_branches`
# number of entries.
#
# A `page` variable is available in the template, which contains the
# current, next, previous, and total number of pages.
#
# Use the "%PAGE%" variable in the `branches` output variable to
# substitute the page number into the produced filename.
paginate_branches = 50
# Whether to split tags output into pages
#
# If non-zero and a `tags` template is specified, the tags output is
# generated several times, each with the `tags` variable in the
# template engine containing the next `paginate_tags` number of
# entries.
#
# A `page` variable is available in the template, which contains the
# current, next, previous, and total number of pages.
#
# Use the "%PAGE%" variable in the `tags` output variable to
# substitute the page number into the produced filename.
paginate_tags = 50
# Whether to render Markdown files in repos into HTML.
#
# Rendering Markdown can make site generation take more time. It has potential
# security implications, as user-generated input (files in the repo) are
# formatted into HTML and served unescaped. Use with caution.
#
# This can also be set per-repository.
render_markdown = true
# Whether render files with syntax highlighting, as HTML.
#
# Applying syntax highlighting is CPU-intensive, and greatly increases site
# generation time. It has potential security implications, as user-generated
# input (files in the repo) are formatted into HTML and served unescaped. Use
# with caution.
#
# This can also be set per-repository.
syntax_highlight = true
# Which theme to use for syntax highlighting colors.
#
# The default themes from Syntect are available, namely:
#
# - `base16-ocean.light`
# - `base16-ocean.dark`
# - `base16-eighties.dark`
# - `base16-mocha.dark`
# - `InspiredGitHub`
# - `Solarized (dark)`
# - `Solarized (light)`
#
syntax_highlight_theme = "base16-ocean.light"
# Whether or not to run 'git fetch' on remote repos
#
# When specified repositories are remote (via HTTPS), this setting
# configures whether Itsy-Gitsy should run the equivalent of `git
# fetch --all` to update the repository first.
#
# Itsy-Gitsy will exit with an error if the fetch fails. If a
# repository is not available, or if Itsy-Gitsy is running in an
# environment without network access, this should be set to 'false'.
#
# This can also be set per-repository. Defaults to 'true' if not
# specified.
fetch_remote = true
# Number of threads to use for parallel processing
#
# Specify a specify a specific number of threads/cores to split
# parallel processing across, or set to 0 to auto-detect.
#
# The most practical values here are 0 (auto-detect, which typically
# means use all cores), or 1 (to disable parallelism).
threads = 0
# Limits maximum number of history items (i.e. git log) to parse.
#
# After the limit is reached, no more history items will be processed or stored
# in memory, and no more commits will be output to disk. For large
# repositories, this can increase processing speed and decrease memory and disk
# usage.
#
# This can also be set per-repository.
#limit_history = 500
# Limits maximum number of commits to output.
#
# When the limit is reached, no more commits are written to disk. Similar to
# `limit_history`, but the entire git log is still read into RAM and provided
# to the templates.
#
# This can also be set per-repository.
#limit_commits = 500
# Limits maximum number of branches to parse.
#
# When the limit is reached, no more branches are parsed in memory or provided
# to the `branch` template.
#
# Since branch order is unsorted and non-deterministic, the most sensible
# values for this are very large, or 0 (to disable branches).
#
# This can also be set per-repository.
#limit_branches = 500
# Limits maximum number of tags to parse.
#
# When the limit is reached, no more tags are parsed in memory or provided to
# the `tag` template.
#
# Since tag order is unsorted and non-deterministic, the most sensible values
# for this are very large, or 0 (to disable tags).
#
# This can also be set per-repository.
#limit_tags = 500
# Limit the `commit_ids` variable to only related commits
#
# Normally the `commit_ids` variable contains a list of *all* git
# commit hashes that Itsy-Gitsy is parsing. For large repos, this can
# be enormous, and take a lot of CPU time to search.
#
# Enabling this option limits `commit_ids` to only contain hashes of
# commits that are referenced by the current object:
#
# - in `history` templates, all commits on the current page
# - in `commit` templates, all the parent commits
# - in `branch` templates, the commit it references
# - in `tag` templates, the commit that it tags
#
# Enabling this provides a performance boost with the default
# templates with no tradeoffs. This is only a restriction for custom
# templates that require more metadata.
#
# This can also be set per-repository.
limit_commit_ids_to_related = true
# Limits directory depth to traverse when parsing files.
#
# Limits the number of directories traversed when enumerating files in the
# `all_files` entry, which is passed as part of the repository to each
# template. This can help reduce RAM usage, and potentially disk usage, for
# repositories with a very large number of files or directories.
#
# Set to 0 to disable both `all_files` and `root_files`, i.e. do not parse any
# file listing. If set to 1 or greater, only applies to `all_files`.
#
# This can also be set per-repository.
#limit_tree_depth = 20
# Limits size of files in repo with content previews.
#
# Only non-binary files smaller than this limit will have their contents
# provided to the `file` template. Large files are still processed, but do not
# include the text contents.
#
# This can also be set per-repository.
#limit_file_size = 2097152
# Limits size of a single produced repository.
#
# Limits the size of a generated repository preview. This is a low-precision
# limit, terminating generation wherever it happens to be, and may lead to many
# dead links in the final output.
#
# This limit is not strict: generation is terminated after the first file that
# exceeds this limit. The output size might somewhat overflow this limit.
# Also, static repository assets specified in this configuration are NOT
# included in this limit.
#
# This is intended merely as a safety mechanism to prevent massive run-away
# disk usage.
#
# This can also be set per-repository.
#limit_repo_size = 52428800
# Limits total size of all output.
#
# Limits the size of the total run: the sum of all repositories. This is a
# low-precision limit, terminating generation wherever it happens to be, and
# may lead to many dead links or entirely missing repositories.
#
# This limit is not strict: generation is terminated after the first file that
# exceeds this limit. The output size might somewhat overflow this limit.
# Also, static repository assets specified in this configuration are NOT
# included in this limit.
#
# This is intended merely as a safety mechanism to prevent massive run-away
# disk usage.
#
# This can also be set per-repository.
#limit_total_size = 524288000
# Limits number of contextual elements available to templates.
#
# By default, if this limit is not set, all repository elements
# (history, branches, tags, commits) are provided in full to all
# repository templates, so every page can see all repo metadata.
#
# For parallel output generation, one copy of the repo metadata is
# made per CPU core. All of this must be loaded into RAM, which means
# large repositories can be very slow to process, or exhaust memory.
#
# This setting limits all elements, *except* those directly relevant
# to the page being rendered. For example, all elements except
# `branches` are limited in the `branches` template, all elements
# except `tags` are limited in the `tags` template, and so on.
#
# This is critically important for very large repositories, to prevent
# them from consuming all memory and destroying all things.
#
# This can also be set per-repository.
#limit_context = 200
# Limit number of diffs and diff statistics.
#
# By default, if this limit is not set, every history item contains
# statistics (files changes, additions, and deletions), and every
# commit item contains a diff. These are all held in memory and
# passed to each repository template.
#
# While parsing history, and if this limit is reached, subsequent
# history and commit items will not have diffs and statistics
# included.
#
# This is critically important for very large repositories, to prevent
# them from consuming all memory and destroying all things.
#
# This can also be set per-repository.
#limit_diffs = 200
###############################################################################
##
## Subsection specifying output paths, and how they are generated.
##
## Itsy-Gitsy requires two root paths, both specified here:
##
## 1) `output_root`, a directory where all rendered output will be written
## 2) `template_root`, a directory where all input templates are stored
##
##
## Next, a `templates` table is defined, which contains a variable
## number of entries. Each entry must contain the following three
## variables:
##
## - `template` -- the input file to use as a template, relative to
## `template_root`
##
## - `output` -- the output file(s) to write, relative to
## `output_root`. These filenames can contain
## variables, which are defined below.
##
## - `kind` -- the type of output being generated. This decides which
## variables are available in the template, and which
## variables can be substituted in the output filename.
##
##
## The following output types are available:
##
## - `repo_list` -- Template receives all defined repository metadata in the `repos` variable.
##
## - `summary` -- Template receives all metadata of the current repo.
## This is split across the `name`, `history`,
## `branches`, `tags`, `root_files`, `all_files`,
## `commits`, `file_ids`, commit_ids`, `metadata`,
## `last_ts_utc`, and `last_ts_offset` variables.
##
## - `history` -- All current repo metadata. `history` variable not
## affected by `limit_context`.
##
## - `commit` -- All current repo metadata. Current commit object in
## `commit` variable.
##
## - `branches` -- All current repo metadata. `branches` variable not
## affected by `limit_context`.
##
## - `branch` -- All current repo metadata. Current branch object in
## `branch` variable.
##
## - `tags` -- All current repo metadata. `tags` variable not
## affected by `limit_context`.
##
## - `tag` -- All current repo metadata. Current tag object in `tag`
## variable.
##
## - `files` -- All current repo metadata.
##
## - `file` -- All current repo metadata. Current file object in
## `file` variable.
##
## - `dir` -- All current repo metadata. Current directory object in
## `dir` variable.
##
## - `error` -- All metadata for all repositories.
##
##
## The following variables are permitted in `output` paths:
##
## - "%REPO%" -- Replaced with the name of the currently processing
## repository. Available in all except `repos_list` and
## `error`.
##
## - "%ID%" -- Replaced with the ID of the currently processing
## object. Available in `commit`, `branch`, `tag`,
## `file`, and `dir`.
##
## - "%PAGE%" -- Replaced with the current page number if output is
## paginated. Available in `history`, `branches`, and
## `tags`.
##
##
## All except `output_root` and `template_root` are optional.
## Template types that are not specified will not be generated, and
## all template types can be generated as many times as desired.
##
###############################################################################
[gitsy_outputs]
output_root = "rendered/"
template_root = "templates/default_light/"
templates = [
{ template = "repos.html", output = "index.html", kind = "repo_list" },
{ template = "summary.html", output = "%REPO%/index.html", kind = "summary" },
{ template = "history.html", output = "%REPO%/history%PAGE%.html", kind = "history" },
{ template = "commit.html", output = "%REPO%/commit/%ID%.html", kind = "commit" },
{ template = "branches.html", output = "%REPO%/branches%PAGE%.html", kind = "branches" },
{ template = "branch.html", output = "%REPO%/branch/%ID%.html", kind = "branch" },
{ template = "tags.html", output = "%REPO%/tags%PAGE%.html", kind = "tags" },
{ template = "tag.html", output = "%REPO%/tag/%ID%.html", kind = "tag" },
{ template = "files.html", output = "%REPO%/files.html", kind = "files" },
{ template = "file.html", output = "%REPO%/file/%ID%.html", kind = "file" },
{ template = "dir.html", output = "%REPO%/dir/%ID%.html", kind = "dir" },
{ template = "404.html", output = "404.html", kind = "error" }
]
# Output file for syntax highlighting CSS
#
# If syntax highlighting is enabled, a single CSS file will be
# rendered to this path. It must be included in the file template to
# render the syntax highlighting correctly.
#
# If not specified, a default is used.
syntax_css = "%REPO%/file/syntax.css"
# Output directory for files specified in global `asset_files`.
#
# Each input file is copied to this directory unmodified.
#
# If not specified, a default is used.
global_assets = "assets/"
# Output directory for files specified in per-repo `asset_files`.
#
# Each input file is copied to this directory unmodified.
#
# If not specified, a default is used.
repo_assets = "%REPO%/assets/"
# Directory to clone remote repositories into.
#
# Remote repositories must be cloned locally to parse. They are cloned into
# subdirectories of `cloned_repos`, as bare git repos. These are not deleted
# when Itsy-Gitsy finishes. If the directories already exist when Itsy-Gitsy
# runs, all remote refs are fetched rather than recloning.
#
# Only non-authenticated HTTPS repositories are currently supported.
#
# If not specified, a default is used.
cloned_repos = "cloned_repos/"
###############################################################################
##
## Subsection for arbitrary, global user data.
##
## These variables are available to every page template. Add extra metadata
## that you want available site-wide here.
##
###############################################################################
[gitsy_extra]
generated_by = "Itsy-Gitsy"
generated_by_url = "https://git.trevorbentley.com/itsy-gitsy/"
#global_user_defined_var = "whatever"
#these_can_also_be_numbers = 5
#or_bools = true
#or_other_toml_types = {like_dicts = "yep, those too"}
###############################################################################
##
## Individual repository configurations.
##
###############################################################################
# The section name is used as the repository name if no `name` attribute is
# provided.
#[my_repository]
# Path to the Git repository.
#path = "/path/to/my_repository"
# Name of this repository, if different from the section name.
#name = "my_repository"
# A description of this repository.
#description = ""
# URL of website associated with this repository.
#website = ""
# Dictionary of arbitrary, user-defined attributes associated with the repo.
#
# Specifying as an inline-table requires all keys to be on one line.
#
# Available in all repo-specific page templates.
#
#attributes = { status = "active", type = "daemon" }
# Per-repository settings, same as the global versions described above:
#clone_url = "https://github.com/your_user/%REPO%"
#branch = "master"
#render_markdown = false
#syntax_highlighting = false
#syntax_highlight_theme = "base16-ocean.dark"
#paginate_history = 50
#paginate_branches = 50
#paginate_tags = 50
#limit_history = 500
#limit_commits = 500
#limit_branches = 500
#limit_tags = 500
#limit_tree_depth = 20
#limit_file_size = 2097152
#limit_repo_size = 52428800
#limit_total_size = 524288000
#limit_context = 200
#limit_diffs = 200
#asset_files = ["%REPO%/LICENSE"]
#readme_files = ["README.md", "README"]
# An alternative way to specify the user-defined attributes.
#
# This method allows keys to be on their own lines.
#
#[circadian.attributes]
#status = "active"
#type = "daemon"
# Remote HTTPS repositories can also be specified:
#
#[remote_repo]
#path = "https://github.com/my_user_name/remote_repo"