############################################################################### ## ## 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"