To render custom file formats using Fossil's embedded TH1 (or full Tcl) interpreter, you configure Fossil's custom mimetype handling mechanism. Fossil checks the mimetype-tile setting (or repository-specific file rendering settings) and invokes configured TH1 scripts to transform raw document content into HTML when viewed via the web interface (/doc, /file, etc.). Step 1: Enable TH1 Hooks (and Tcl if needed) Fossil restricts TH1 capabilities by default for security.

Allow TH1 execution on web pages / docs: fossil set th1-hooks 1
(Optional) Enable Tcl integration: If your renderer requires capabilities beyond mini-TH1 (e.g., complex regex, file I/O, or calling external CLI tools like Pandoc or Graphviz via exec), Fossil must be compiled with --with-tcl. Then enable Tcl evaluation: fossil set tcl 1

Step 2: Associate File Extensions with a Custom MIME Type Fossil maps file extensions to MIME types using the mimetype-override setting or a repository table. Set an extension override (e.g., mapping .custom to text/x-custom): fossil set mimetype-override "custom: text/x-custom"

Note: If you have multiple extensions, delimit them with newlines or specify them via the web UI under Admin to Settings to mimetype-override. Step 3: Configure the Custom Renderer Script Fossil supports defining a TH1 script to render documents matching specific MIME types or path patterns. This is commonly done through the th1-setup script or the custom document rendering hook. Navigate to Admin to Settings to th1-setup (or run fossil set th1-setup ...). Option A: Pure TH1 Renderer TH1 includes basic string manipulation, variable handling, and the html / puts commands:

Check the requested mimetype or file extension

if {[info exists current_page] && $current_page eq "doc"} { # Example: intercept rendering if the file matches custom criteria }

For direct MIME rendering, Fossil inspects the page rendering pipeline. When rendering formatted text, Fossil provides built-in commands like render and allows TH1 script intervention. Option B: Bridging to Tcl for Complex Formatting If you need a dedicated parser or external tool, use the tclEval command inside TH1:

Inside your th1-setup or custom hook:

proc render_custom {content} { set script [string map [list %CONTENT% $content] { # Tcl code block package require Html # Perform parsing or call an external CLI tool set rendered [exec /usr/local/bin/my-parser << {%CONTENT%}] return $rendered }] return [tclEval $script] }

Step 4: Intercepting the Document View (/doc or /file) Fossil natively routes specific mimetypes like text/markdown, text/x-fossil-wiki, and text/plain through internal renderers. For an arbitrary new MIME type:

Using /doc Script Interception: Fossil allows you to serve dynamic pages via /doc if you include a .th1 file or embed TH1 within the document, provided th1-hooks is enabled.
Custom URL handler via TH1: In th1-setup, you can define custom TH1 procedures that intercept page requests. When a user requests /doc/trunk/example.custom, Fossil passes the artifact payload into the environment. You can extract the raw artifact content using: set raw_content [artifact $rid]

Transform the payload with your renderer procedure, and output the generated HTML: html "

" html $rendered_html html "

Alternative: Custom CGI/Extension Page If you want a dedicated route rather than modifying built-in MIME dispatch:

Add an extension page in repository settings (Admin to Pages).
Point a path like custom_view to a TH1 script or external CGI script.
Fetch the file version via the repository artifact query and pipe it to your renderer.