Configuration

Keecas uses a hierarchical TOML configuration system that allows you to customize behavior globally and per-project.

Configuration Files

File Locations

Global: ~/.keecas/config.toml (applies to all projects)
Local: <project>/.keecas/config.toml (project-specific settings)

Priority Order

Local config overrides global config, which overrides built-in defaults:

Local > Global > Defaults

CLI Configuration Management

Keecas provides a comprehensive CLI for managing configurations:

Initialize Configuration

# Create global configuration file
keecas config init --global

# Create local configuration file (in current project)
keecas config init --local

# Force overwrite existing config
keecas config init --global --force

Edit Configuration

# Edit with terminal editor ($EDITOR)
keecas config edit --global
keecas config edit --local

# Open with system default editor (GUI)
keecas config open --global
keecas config open --local

View Configuration

# Show merged configuration (local + global + defaults)
keecas config show

# Show only global configuration
keecas config show --global

# Show only local configuration
keecas config show --local

# Show configuration file paths
keecas config path

Reset Configuration

# Reset to defaults
keecas config reset --global
keecas config reset --local --force

Other Commands

# Show configuration version information
keecas config version

# Manually trigger configuration migration (when upgrading keecas)
keecas config migrate

Configuration Options

Configuration File Structure

Configuration uses nested TOML sections. Settings are organized by category:

[latex]: LaTeX equation formatting (eq_prefix, environments, etc.)
[display]: Display behavior (katex, debug, float formats, etc.)
[language]: Language and localization settings
[translations]: Custom term translations
[check_templates]: Verification function templates

Example Configuration File

# .keecas/config.toml

# Top-level language setting
language = "en"                    # Supported: de, es, fr, it, pt, en

[latex]
# LaTeX equation generation
eq_prefix = "eq-"                  # Equation label prefix
eq_suffix = ""
default_environment = "align"

[display]
# Display and formatting
katex = false                      # KaTeX compatibility mode
print_label = false                # Print labels in development
default_float_format = ".3f"       # Default format for float values
pint_default_format = ".2f~P"      # Pint quantity formatting

[language]
# Language settings
disable_pint_locale = true         # Preserve compact unit symbols (kN vs kilonewton)

[translations]
# Custom term translations
"VERIFIED" = "VERIFIED"
"Domain" = "Domain"

Language Support

Keecas supports multiple languages with automatic Pint unit locale synchronization:

Fully Supported Languages (5)

German (de): Complete translations + localized units
Spanish (es): Complete translations + localized units
French (fr): Complete translations + localized units
Italian (it): Complete translations + localized units
Portuguese (pt): Complete translations + localized units

Fallback Languages (5)

Danish (da), Dutch (nl), Norwegian (no), Swedish (sv): English units with term translations
English (en): Default behavior

Key Settings

Setting	Default	Description
`language.language`	`"en"`	Language for UI and units
`display.katex`	`false`	Enable KaTeX compatibility
`latex.eq_prefix`	`"eq-"`	Prefix for equation labels
`display.print_label`	`false`	Show labels during development
`display.default_float_format`	`None`	Default format for float values (e.g., “.3f”)
`display.pint_default_format`	`".2f~P"`	Number formatting for units
`language.disable_pint_locale`	`true`	Disable automatic locale changes

In-Code Configuration

You can also modify configuration directly in your notebooks:

from keecas import config

# Change language (automatically updates Pint locale)
config.language.language = 'it'

# Enable KaTeX mode for VS Code compatibility
config.display.katex = True

# Customize equation labeling
config.latex.eq_prefix = 'eq-custom-'
config.display.print_label = True

# Float formatting
config.display.default_float_format = '.3f'

# View current settings
print(config.to_dict())

Jupyter Notebook Setup

If you plan to use only jupyter notebooks without rendering with Quarto, no special configuration is required¹

from keecas import symbols, u, pc, show_eqn, config, check

# Configure for your environment only if different from the global/local config.toml
config.language.language = 'es'              # Set your language

# Initialize global containers (in needed)
params = {}  # Global parameters
eqn = {}     # Global expressions

Quarto Integration

Quarto automatically includes amsmath and amssymb packages in PDF output through its default LaTeX template, so no additional configuration is needed for PDF rendering.

For HTML output with equation numbering and cross-references, add MathJax configuration to your YAML header:

---
title: "My Engineering Calculation"
format:
  html:
    include-in-header:
      # Enable equation numbering and labeling
      - text: |
          <script>
          MathJax = { tex: { tags: 'ams' } };
          </script>
      # Prevent horizontal scrollbars on equations
      - text: |
          <style>
          .math.display {
            max-width: 100%;
            padding-right: 3em;
          }
          </style>
  pdf: default
---

Then in your first code cell:

from keecas import *

# set a namespace for the expression in the following section. Update this as needed
config.latex.eq_prefix = 'eq-<namespace>-'

Add a code cell with #| eval: false to set specific configuration you may want when developing your notebook, but don’t want to run when rendered by Quarto.

#| eval: false

# disable `\label command` when KaTeX is the rendering engine to avoid ParseError
config.display.katex = True

# print interpolated labels for easy reference (e.g. copy and paste) 
config.display.print_label = True 

# print the latex interpolated source for all show_eqn calls
config.display.debug = True

Custom LaTeX Environments

Define custom environments in your config file or code:

# In .keecas/config.toml
[latex.environments.spaced_align]
separator = "&"
line_separator = " \\\\[0.5em]\n "
supports_multiple_labels = true
outer_environment = "align"

# In Python
config.latex.environments.set("custom", {
    "separator": "&",
    "line_separator": " \\\\\n ",
    "supports_multiple_labels": True,
    "outer_environment": "align"
})

# Use in show_eqn
show_eqn(equations, environment="custom")

Troubleshooting

Configuration Not Loading

Check file paths and permissions:

# Show where Keecas looks for config files
keecas config path

# Verify file exists and is readable
cat ~/.keecas/config.toml

# open the file in your editor
keecas config open [--global/--local]

Language Changes Not Applied

Translations are simply match/replace operations using a limited dictionary where the key is the english term (default) and value is the translated term.

If a term does not get translated in one of the supported languages, then is not present in the dict. Please open an issue with the term you want to translate.

Invalid TOML Syntax

Use the CLI to validate configuration:

# This will show parsing errors
keecas config show

Next Steps

With configuration set up, you’re ready to:

Explore the API Reference for complete function documentation
Check out example notebooks for real-world usage patterns

Footnotes

config.display.katex is only relevant is you’re using labels, but labels only make sense when rendering with Quarto↩︎