🪄 gtext

The text wizard - Transform text files with pluggable extensions.

---

✨ What is gtext?

gtext is a universal text processor with a pluggable extension system. Transform any text file through customizable plugins:

• 📝 Include files (static, dynamic, glob patterns)
• 🤖 AI processing (summarization, translation)
• 💻 Code generation (headers, boilerplate)
• ✅ Validation (links, spelling)
• 🔄 And much more...

Created by the Genro Team. Universal and standalone.

---

🚀 Quick Start

Installation

pip install gtext

Basic Usage

File Extension Convention

gtext uses the .gtext extension to identify source files:

# Double extension (auto-detect output format)
document.md.gtext  → document.md
script.py.gtext    → script.py
config.yaml.gtext  → config.yaml

Example

Source file (report.md.gtext):

# Monthly Report

## Company Stats

```include
cli: python scripts/get_stats.py --format markdown
```

## Team Structure

```include
docs/team-structure.md
```

## All Project Docs

```include
glob: projects/**/README.md
```

Generate expanded document:

# Auto-detect output (strip .gtext extension)
gtext render report.md.gtext

# Or specify output file/directory
gtext render report.md.gtext report.md
gtext render report.md.gtext output/

# Process multiple files or patterns
gtext render "docs/**/*.gtext" output/

Re-render after changes (using saved metadata):

# Modify report.md.gtext, then refresh
gtext refresh report.md.gtext

# Or refresh all .gtext files with saved outputs
gtext refresh

Result (report.md):

# Monthly Report

## Company Stats

| Metric | Value |
|--------|-------|
| Revenue | $1.2M |
| Users | 10,453 |

## Team Structure

[content from docs/team-structure.md]

## All Project Docs

[all README.md files from projects/**/]

🆕 New in v0.2.0: The render command now intelligently handles single files, multiple files, and patterns. The old cast and cast-all commands are deprecated (but still work) and will be removed in v0.3.0.

---

📓 Learning with Interactive Tutorials

The best way to learn gtext is through our hands-on Jupyter notebooks.

Run Online (No Installation Required)

Click the badge above to launch an interactive Jupyter environment in your browser. Ready in ~2 minutes!

Run Locally

# 1. Install Jupyter
pip install jupyter notebook

# 2. Navigate to notebooks directory
cd notebooks

# 3. Launch Jupyter
jupyter notebook

# 4. Open 01_rag_prompt_engineering.ipynb and start learning!

Tutorial Contents

Notebook	Topic	Duration	Level
01 - RAG & Prompt Engineering	AI/LLM integration, composable prompts	30 min	Intermediate

More tutorials coming soon! See notebooks/README.md for the complete learning guide.

---

🎯 Key Features

1. Include Static Files

```include
path/to/file.md

### 2. Include Command Output

```markdown
```include
cli: genro project list --format markdown

### 3. Include Multiple Files with Glob

```markdown
```include
glob: docs/**/*.md

### 4. Mix All Types

```markdown
```include
header.md
cli: python get_stats.py
glob: sections/*.md
footer.md

---

## 🔐 Security

gtext implements a **secure-by-default** policy for all includes and command executions. Everything is **denied unless explicitly allowed** through configurable rules.

### Quick Security Setup

```bash
# Allow safe read-only commands (global)
gtext config :cli add_rule "date" allow --global
gtext config :cli add_rule "git status" allow --global
gtext config :cli add_rule "ls*" allow --global

# Allow markdown file includes
gtext config :static add_rule "*.md" allow --global

# Block dangerous commands (explicitly deny)
gtext config :cli add_rule "rm *" deny --global

# View your security configuration
gtext config show

Key Security Features

• 🛡️ Secure by Default: Nothing runs without explicit permission
• 📋 Ordered Rules: First-match wins pattern (like firewall rules)
• 🎯 Protocol-Specific: Independent rules for cli:, static:, glob: protocols
• 🌍 Global & Project: System-wide rules + project-specific overrides
• ⚠️ Dangerous Characters: Metacharacters (;, &, |, $) always blocked

Rule Evaluation (First-Match Wins)

Rules are checked in order and stop at the first match:

Configuration:
0: git push* → deny      # Block pushes
1: git * → allow         # Allow other git commands

Command: git push        → DENIED by rule 0 (stops here)
Command: git status      → ALLOWED by rule 1

Critical: Order matters! Put specific rules before general ones.

Documentation

New to gtext security? Start here: QUICKSTART-SECURITY.md (5-minute guide)

Full security documentation: SECURITY.md

Topics covered:

• Complete CLI command reference
• Rule management (add, remove, reorder)
• Pattern matching with wildcards
• Global vs project configuration
• Best practices and examples
• Troubleshooting guide

---

📚 Use Cases

Documentation

• Living docs that update from real data
• Multi-file documentation aggregation
• Auto-generated API docs from code

Code Management

• License headers across codebase
• Boilerplate injection
• Shared imports and configs

Reporting

• Dynamic reports with live database queries
• System monitoring snapshots
• Business dashboards in Markdown

Content Management

• Blog post templates with includes
• Multi-language content
• Reusable content blocks

---

🛠️ CLI Commands

Rendering & Processing

# Render single file (auto-detect output)
gtext render document.md.gtext

# Explicit output path
gtext render document.md.gtext output.md

# Render to output directory
gtext render document.md.gtext output/

# Render multiple files or patterns
gtext render "docs/**/*.gtext" output/

# Refresh using saved metadata
gtext refresh document.md.gtext

# Refresh all files with metadata
gtext refresh

# Dry run (preview without writing)
gtext render document.md.gtext --dry-run

# Live preview server (auto-refresh on file changes)
gtext serve document.md.gtext
gtext serve document.md.gtext --port 8000

Note: The serve command requires installing the optional dependency:

pip install 'gtext[serve]'

Security Configuration

# View security configuration
gtext config show                           # Merged (global + project)
gtext config show --json                    # JSON format
gtext config :cli list_rules --global       # List global rules

# Add security rules
gtext config :cli add_rule "date" allow --global
gtext config :cli add_rule "git *" allow --name "allow_git" --global
gtext config :static add_rule "*.md" allow

# Remove rules (by index or name)
gtext config :cli remove_rule 0 --global
gtext config :cli remove_rule "allow_git" --global

# Reorder rules (critical for first-match evaluation!)
gtext config :cli rule 2 up --global        # Move rule up
gtext config :cli rule 0 down --global      # Move rule down
gtext config :cli rule 3 top --global       # Move to top
gtext config :cli rule 0 bottom --global    # Move to bottom

# Clear all rules for a protocol
gtext config :cli clear_rules --global

See SECURITY.md for complete documentation.

---

🔌 Plugin System

gtext is built on a pluggable architecture. Extensions are easy to create:

from gtext.extensions import BaseExtension

class MyExtension(BaseExtension):
    name = "my-plugin"

    def process(self, content: str, context: dict) -> str:
        # Your transformation logic
        return transformed_content

Built-in extensions:

• include - Include static files
• include-cli - Include command output
• include-glob - Include files matching patterns

Future extensions:

• ai-summarize - AI-powered summarization
• ai-translate - Multi-language translation
• validate-links - Check for broken links
• generate-toc - Auto table of contents
• And more...

---

📖 Documentation

Full documentation available at: gtext.readthedocs.io

• Installation
• Quick Start
• Extensions Guide
• API Reference
• Examples

---

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

---

🎖️ Attribution (Optional)

If gtext helps your project, consider showing support:

Add a badge:

[![Made with gtext](https://img.shields.io/badge/made%20with-gtext-7c3aed?style=flat-square&logo=markdown&logoColor=white)](https://github.com/genropy/gtext)

Preview:

Or mention in your docs:

*Documentation generated with [gtext](https://github.com/genropy/gtext)*

See docs/attribution.md for more options.

⭐ Star us on GitHub to show support!

---

📜 License

MIT License - see LICENSE for details.

No attribution required - but appreciated! 🙏

---

🌟 About

gtext is created by Giovanni Porcari with contributions from the Genro Team.

Like a weaverbird 🪶 that masterfully weaves materials together, gtext weaves different content sources into unified documents.

gtext is:

• ✅ Standalone - No dependencies on other frameworks
• ✅ Universal - Works with any text format
• ✅ Open - MIT licensed and community-driven

---

🔗 Links

• GitHub: github.com/genropy/gtext
• PyPI: pypi.org/project/gtext
• Documentation: gtext.readthedocs.io
• Issues: github.com/genropy/gtext/issues
• Genro Project: github.com/genropy/genro-next-generation

---

Made with ✨ by the Genro Team