gtext 0.2.0

The text wizard - Transform text files with pluggable extensions

🪄 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

---

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

```bash
# Expand single file (auto-detect output)
gtext cast document.md.gtext

# Explicit output path
gtext cast document.md.gtext -o output.md

# Expand all .gtext files in directory
gtext cast-all docs/**/*.gtext

# Watch mode (auto-regenerate on changes)
gtext watch docs/**/*.gtext

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

---

🔌 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.

---

📜 License

MIT License - see LICENSE for details.

---

🌟 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