ctxssg 0.0.2

contextual docs

ctxssg

A pandoc-based static site generator designed for technical documentation and content that requires structured output in multiple formats.

Features

Core Capabilities

• Multi-format Output: Generate HTML, XML, JSON, and plain text from single source files
• Pandoc Integration: Leverage pandoc's powerful document conversion with syntax highlighting
• Template-driven Architecture: Jinja2-based templating with customizable output formats
• TOML Configuration: Modern configuration with format-specific options
• Live Development Server: Hot-reload development environment with file watching

Installation

Prerequisites

• Python 3.10+
• Pandoc (required for document conversion)

Install

uv tool install ctxssg

via Pip

pip install ctxssg

Verify Installation

ctxssg doctor  # Check system dependencies and configuration

Quick Start

1. Initialize Site

ctxssg init my-docs --title "Technical Documentation"
cd my-docs

2. Configure Output Formats

Edit config.toml to enable multiple formats:

[build]
output_formats = ["html", "xml", "json", "plain"]

[formats.json]
pretty_print = true
include_metadata = true

[formats.xml]
include_namespaces = false

3. Create Content

ctxssg new "API Reference" --type page
ctxssg new "Getting Started" --type post

4. Build and Serve

ctxssg build    # Generate all configured formats
ctxssg serve    # Development server with hot-reload

Architecture

Project Structure

my-docs/
├── config.toml              # TOML configuration
├── content/                 # Source content
│   ├── posts/              # Blog posts/articles
│   │   └── *.md
│   └── *.md                # Static pages
├── templates/               # Jinja2 templates
│   ├── base.html           # Base HTML template
│   ├── default.html        # Default page template
│   ├── index.html          # Homepage template
│   ├── post.html           # Post template
│   └── formats/            # Output format templates
│       ├── document.xml.j2 # XML output template
│       ├── document.json.j2# JSON output template
│       └── document.txt.j2 # Plain text template
├── static/                  # Static assets
│   ├── css/
│   └── js/
└── _site/                   # Generated output
    ├── *.html              # HTML files
    ├── *.xml               # XML files
    ├── *.json              # JSON files
    └── *.txt               # Plain text files

Content Format

Content files use Markdown with YAML frontmatter:

---
title: API Authentication
date: 2024-01-15
layout: default
tags: [api, auth, security]
---

# Authentication

API authentication is handled via...

## OAuth 2.0 Flow

1. Obtain authorization code
2. Exchange for access token
3. Include token in requests

Configuration

Basic Configuration (config.toml)

[site]
title = "Technical Documentation"
url = "https://docs.example.com"
description = "Comprehensive API and development documentation"
author = "Development Team"

[build]
output_dir = "_site"
output_formats = ["html", "xml", "json", "plain"]

[formats.json]
pretty_print = true
include_metadata = true

[formats.xml]
include_namespaces = false

[formats.plain]
include_metadata = true
wrap_width = 80

Template Customization

Override default templates by creating files in your templates/ directory. Templates use Jinja2 syntax with access to:

• site - Site configuration
• page - Current page data
• content - Structured content data (for format templates)
• metadata - Page metadata

Format Templates

Create custom output formats by modifying templates in templates/formats/:

• document.xml.j2 - XML output structure
• document.json.j2 - JSON API response format
• document.txt.j2 - Plain text documentation

CLI Commands

Site Management

ctxssg init [path] --title "Site Title"     # Initialize new site
ctxssg build                                # Build all configured formats
ctxssg serve --port 8000 --watch           # Development server
ctxssg doctor                               # System diagnostics

Content Creation

ctxssg new "Page Title" --type page         # Create new page
ctxssg new "Post Title" --type post         # Create new post
ctxssg convert input.md --format xml        # Convert single file

Development Commands

ctxssg serve --watch                        # Hot-reload development
ctxssg build --watch                        # Continuous building

Output Formats

HTML

Standard web output with responsive design, syntax highlighting, and navigation.

XML

Structured XML output suitable for API consumption:

<document>
  <metadata>
    <title>API Reference</title>
    <date>2024-01-15</date>
  </metadata>
  <content>
    <section id="authentication" level="1">
      <title>Authentication</title>
      <content>...</content>
    </section>
  </content>
</document>

JSON

API-friendly JSON structure:

{
  "metadata": {
    "title": "API Reference",
    "date": "2024-01-15"
  },
  "content": {
    "sections": [
      {
        "id": "authentication",
        "level": 1,
        "title": "Authentication",
        "content": [...]
      }
    ]
  }
}

Plain Text

Clean text output for documentation systems and CLIs.

Advanced Usage

Custom Templates

Create format-specific templates for specialized output:

{# templates/formats/api-spec.json.j2 #}
{
  "apiVersion": "v1",
  "kind": "Documentation",
  "metadata": {{ metadata | tojson }},
  "spec": {
    "sections": [
      {% for section in content.sections %}
      {
        "name": "{{ section.title }}",
        "content": "{{ section.content | join(' ') }}"
      }{% if not loop.last %},{% endif %}
      {% endfor %}
    ]
  }
}

Batch Processing

Process multiple files programmatically:

from ctxssg.generator import Site
from pathlib import Path

site = Site(Path("my-docs"))
site.build()  # Generate all formats

Development

Setup Development Environment

git clone https://github.com/kgruel/ctxssg.git
cd ctxssg
python -m venv venv
source venv/bin/activate  # or `venv\Scripts\activate` on Windows
pip install -e '.[dev]'

Run Tests

python -m pytest                    # Run test suite
ruff check .                       # Lint code
ruff format .                      # Format code

Project Architecture

• ctxssg/generator.py - Core site generation logic
• ctxssg/cli.py - Command-line interface
• ctxssg/templates/ - Package template resources
• ctxssg/assets/ - Default CSS and static assets

Requirements

System Dependencies

• Pandoc: Document conversion engine
• Python 3.10+: Modern Python with typing support

Python Dependencies

• click - CLI framework
• jinja2 - Template engine
• pypandoc - Pandoc integration
• pyyaml - YAML configuration support
• tomli - TOML configuration support
• python-frontmatter - Frontmatter parsing
• beautifulsoup4 - HTML parsing
• watchdog - File system monitoring

License

Apache-2.0

Contributing

Contributions are welcome! Please read the contributing guidelines and submit pull requests for any enhancements.