VIBE Template Author's Guide¶

Welcome to the official documentation for creating templates with VIBE. This guide is designed for subject matter experts, not programmers, and will walk you through everything from the basics to advanced features. Assistant and Review are optional extensions; this guide focuses on core template authoring first, with extension guides listed separately.

Start with the introduction or jump directly to the section you need.

Basic¶

1. Introduction to VIBE

   • A high-level overview of what VIBE is and the problems it solves for authors.

2. Building a VIBE Template: A Step-by-Step Tutorial

   • A comprehensive, hands-on guide to building a template from the ground up, covering basic and advanced features.

3. Core Concepts

   • Explains the fundamental pillars: the config.yml file, the Template file, Session Context, and the VIBE Engine.

4. Template Authoring Guide (Jinja Essentials)

   • A curated guide to the most essential Jinja commands for use in your .md or .docx files.

5. DOCX Authoring Guide

   • Practical guidance for Word-first template authors: where Jinja tags go, what formatting survives, and how to debug DOCX-specific issues.

6. The Question Types Reference

   • A detailed dictionary of every available question type (text, number, date, list, etc.) and their options.

Intermediate¶

1. Reusable Data with definitions

   • Create reusable data structures, recursive composition, and definition-driven questions.

2. Reuse with Components

   • Create and use reusable components with {{ insert() }}: from simple snippets to configurable clause libraries with their own interviews.

3. Session Context

   • Learn how to use pre-filled data from authentication tokens or administrator configuration in your templates.

4. Linked Interviews

   • Connect interviews with recommend() so follow-up templates can start with shared, read-only data.

5. Automated Calculations with Computable Variables

   • Complete guide to computable variables: inline expressions, function-based computations, automatic dependency tracking, and conditional logic.

6. Generating Appendices and Annexes

   • Learn how to create separate documents like appendices, annexes, or schedules that are generated alongside your main template using the {{ appendix() }} function.

7. Grouped Interviews

   • Organize long interviews into groups and choose a presentation layout (paged, accordion, tabs, flat).

8. What’s New in the Component System

   • Overview of the newer component collection patterns, question placement controls, and input scoping behavior.

9. Linguistic Template Features

   • Features to help you correctly handle plurals, possessives, and complex list formatting in your templates that adapts to their users' answers (for all VIBE supported languages).

10. Template Functions, Filters & Metadata

    • Built-in functions, filters, and metadata available in every template, plus how to add your own with templatefunctions.py and templatefilters.py.

11. Cross-References and Section Numbering

    • How to create internal links ("see section 3.2") that stay correct when conditional sections shift the numbering, in both Markdown and Word templates.

12. Customizing the Interview UI

    • Override individual HTML fragments or attach per-template CSS without touching the global app.

13. Best Practices and Common Patterns

    • A collection of recommended approaches for building robust, maintainable, and easy-to-understand templates.

14. Common Recipes

    • Copy-pasteable patterns for recurring tasks like optional clauses, followups, grouped interviews, computables, and cross-references.

Reference¶

1. Template Metadata Reference

   • Access session information, timestamps, template details, and AI assistant usage data from within your templates for audit trails, troubleshooting, and transparency.

2. Configuration file reference

   • A reference of all keys/settings that can be used in the various configuration files.

3. Command-Line Tools for Authors

   • A reference for the validate and inspect tools that help you build and debug templates faster.

4. Behavioral Template Testing

   • Define expected outcomes for your templates and verify them automatically with vibe test.

5. Developer Toolkit (vibe-dev)

   • A suite of tools for troubleshooting the VIBE system, performing code management tasks like file concatenation, and directly manipulating .docx files

6. Troubleshooting Guide

   • A symptom-based guide to solving the most common issues like "Why isn't my question showing up?".

7. Glossary

   • Simple, clear definitions of VIBE-specific terms like component, definition, and probe.

Extensions (Optional)¶

The following guides require the corresponding extension to be enabled:

• Author Extension
  • Create and edit templates directly in the browser with a visual workspace, live preview, drag-and-drop question ordering, and Microsoft Word integration.
• Create drafting assistants
  • Integrate interactive Large Language Model (LLM) assistants into your templates, helping the user to draft complex, creative, or context-dependent sections.
• Interactive assistant tutorial
  • Hands-on tutorial for building assistant-driven templates.
• Document Review
  • Build review templates that evaluate existing documents against requirements.

Developer Resources¶

The following documentation is intended for developers and system administrators:

• Environment Variables
  • Configuration options for the VIBE server environment, including debug mode, authentication, and deployment settings.
• Developer Toolkit (vibe-dev)
  • Debugging and utility tools for VIBE system development and troubleshooting.