{"id":33571875,"url":"https://github.com/lbliii/bengal","last_synced_at":"2026-04-10T04:18:31.526Z","repository":{"id":317779456,"uuid":"1068781670","full_name":"lbliii/bengal","owner":"lbliii","description":"ᓚᘏᗢ Bengal — High-performance static site generator for Python 3.14+ with parallel builds, autodoc, and content validation","archived":false,"fork":false,"pushed_at":"2026-02-07T22:05:45.000Z","size":33999,"stargazers_count":27,"open_issues_count":1,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-08T01:48:34.980Z","etag":null,"topics":["api-documentation","autodoc","bengal","blog","docs","documentation","documentation-tool","html-css-javascript","incremental-builds","jinja2","live-reload","markdown","pages","python","python-3-14-gil-free","ssg","static","static-site","static-site-generator"],"latest_commit_sha":null,"homepage":"https://lbliii.github.io/bengal/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lbliii.png","metadata":{"files":{"readme":"README.md","changelog":"changelog.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-02T22:41:46.000Z","updated_at":"2026-02-07T22:05:48.000Z","dependencies_parsed_at":"2025-10-30T01:26:01.680Z","dependency_job_id":null,"html_url":"https://github.com/lbliii/bengal","commit_stats":null,"previous_names":["lbliii/bengal"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/lbliii/bengal","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lbliii%2Fbengal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lbliii%2Fbengal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lbliii%2Fbengal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lbliii%2Fbengal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lbliii","download_url":"https://codeload.github.com/lbliii/bengal/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lbliii%2Fbengal/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29255400,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-09T01:52:29.835Z","status":"online","status_checked_at":"2026-02-09T02:00:09.501Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-documentation","autodoc","bengal","blog","docs","documentation","documentation-tool","html-css-javascript","incremental-builds","jinja2","live-reload","markdown","pages","python","python-3-14-gil-free","ssg","static","static-site","static-site-generator"],"created_at":"2025-11-28T10:06:28.481Z","updated_at":"2026-04-10T04:18:31.518Z","avatar_url":"https://github.com/lbliii.png","language":"Python","funding_links":[],"categories":["Uncategorized","By Language","Site Generators"],"sub_categories":["Uncategorized","Python"],"readme":"# ᓚᘏᗢ Bengal\n\n[![PyPI version](https://img.shields.io/pypi/v/bengal.svg)](https://pypi.org/project/bengal/)\n[![Build Status](https://github.com/lbliii/bengal/actions/workflows/tests.yml/badge.svg)](https://github.com/lbliii/bengal/actions/workflows/tests.yml)\n[![Python 3.14+](https://img.shields.io/badge/python-3.14+-blue.svg)](https://pypi.org/project/bengal/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n[![Status: Alpha](https://img.shields.io/badge/status-alpha-orange.svg)](https://pypi.org/project/bengal/)\n\n**The documentation generator built on Python's free-threading future**\n\nEvery layer — markdown parsing, syntax highlighting, templates, dev server — is pure Python, scales with your cores, and ships zero npm dependencies.\n\n```bash\npip install bengal\nbengal new site mysite \u0026\u0026 cd mysite \u0026\u0026 bengal serve\n```\n\n---\n\n## Why Bengal?\n\nBengal is a static site generator where the entire stack is Python you can read, debug, and extend. No JavaScript toolchains. No compiled C extensions in the critical path. Every library in the pipeline — [Patitas](https://github.com/lbliii/patitas) (markdown), [Rosettes](https://github.com/lbliii/rosettes) (syntax highlighting), [Kida](https://github.com/lbliii/kida) (templates), [Pounce](https://github.com/lbliii/pounce) (dev server) — is purpose-built for Python 3.14+ free-threading.\n\n**What this gets you:**\n\n- **Scales with cores** — Parallel builds with true thread parallelism on Python 3.14t. No GIL contention.\n- **AI-native output** — Generates [llms.txt](https://llmstxt.org/), agent manifests, per-page JSON, and [Content Signals](https://contentsignals.org/) so AI agents can discover, navigate, and respect your content policies.\n- **Sub-second rebuilds** — Provenance-based incremental builds with content-addressed hashing. Only changed pages rebuild.\n- **Python-native workflows** — Jupyter `.ipynb` rendering, autodoc for Python/CLI/OpenAPI, `pip install` and go.\n- **Batteries included** — Sitemap, RSS, social cards, search indexes, broken link detection, content validation.\n- **Extensible** — Pluggable engines for templates, Markdown, and syntax highlighting. 9 plugin extension points.\n\n## Use Bengal For\n\n- **Documentation sites** — Versioned docs, API reference, search, and internal linking\n- **Blogs and journals** — Tags, categories, feeds, related content, and social sharing\n- **Knowledge bases** — Markdown-first publishing with validation and JSON search indexes\n- **Product and marketing sites** — Landing pages, content collections, and social cards\n\n---\n\n## Quick Commands\n\n| Command | Description |\n|---------|-------------|\n| `bengal build` | Production build |\n| `bengal serve` | Dev server with live reload |\n| `bengal validate` | Health checks and validation |\n| `bengal fix` | Auto-fix common issues |\n| `bengal graph report` | Site structure analysis |\n\nAliases: `b` (build), `s` (serve), `v` (validate)\n\n---\n\n## Site Scaffolding\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eInteractive Wizard\u003c/strong\u003e — Guided setup with presets\u003c/summary\u003e\n\nRun without arguments for a guided experience:\n\n```bash\nbengal new site\n```\n\nThe wizard prompts for site name, base URL, and presents preset options:\n\n```\n🎯 What kind of site are you building?\n  📝 Blog            - Personal or professional blog\n  📚 Documentation   - Technical docs or guides\n  💼 Portfolio       - Showcase your work\n  🛒 Product         - Product site with listings and features\n  📄 Resume          - Professional resume/CV site\n  📦 Blank           - Empty site, no initial structure\n  ⚙️  Custom         - Define your own structure\n```\n\nEach preset creates a complete site with appropriate sections, sample content, and configuration.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eDirect Template Selection\u003c/strong\u003e — Skip prompts with explicit options\u003c/summary\u003e\n\nCreate sites non-interactively with `--template`:\n\n```bash\nbengal new site my-docs --template docs\nbengal new site my-blog --template blog\nbengal new site portfolio --template portfolio\n```\n\n**Available templates:**\n\n| Template | Description | Sections Created |\n|----------|-------------|------------------|\n| `default` | Basic site structure | Home page only |\n| `blog` | Personal/professional blog | blog, about |\n| `docs` | Technical documentation | getting-started, guides, reference |\n| `portfolio` | Showcase work | about, projects, blog, contact |\n| `product` | Product site with listings | products, features, pricing, contact |\n| `resume` | Professional CV | Single resume page |\n| `landing` | Single-page landing | Home, privacy, terms |\n| `changelog` | Release notes timeline | Changelog with versions |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eAdd Sections to Existing Sites\u003c/strong\u003e — Expand without recreating\u003c/summary\u003e\n\nAdd new content sections to an existing Bengal site:\n\n```bash\n# Add multiple sections\nbengal init --sections docs --sections tutorials\n\n# Add sections with sample content\nbengal init --sections blog --with-content --pages-per-section 5\n\n# Preview without creating files\nbengal init --sections api --dry-run\n```\n\n**Section type inference:**\n\n| Name Pattern | Inferred Type | Behavior |\n|--------------|---------------|----------|\n| blog, posts, articles, news | `blog` | Date-sorted, post-style |\n| docs, documentation, guides, tutorials | `doc` | Weight-sorted, doc-style |\n| projects, portfolio | `section` | Standard section |\n| about, contact | `section` | Standard section |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eCustom Skeleton Manifests\u003c/strong\u003e — YAML-defined site structures\u003c/summary\u003e\n\nFor complex or repeatable scaffolding, define structures in YAML manifests:\n\n```bash\n# Preview what would be created\nbengal project skeleton apply my-structure.yaml --dry-run\n\n# Apply the skeleton\nbengal project skeleton apply my-structure.yaml\n\n# Overwrite existing files\nbengal project skeleton apply my-structure.yaml --force\n```\n\n**Example manifest** (`docs-skeleton.yaml`):\n\n```yaml\nname: Documentation Site\ndescription: Technical docs with navigation sections\nversion: \"1.0\"\n\ncascade:\n  type: doc  # Applied to all pages\n\nstructure:\n  - path: _index.md\n    props:\n      title: Documentation\n      description: Project documentation\n      weight: 100\n    content: |\n      # Documentation\n      Welcome! Start with our [Quick Start](getting-started/quickstart/).\n\n  - path: getting-started/_index.md\n    props:\n      title: Getting Started\n      weight: 10\n    cascade:\n      type: doc\n    pages:\n      - path: installation.md\n        props:\n          title: Installation\n          weight: 20\n        content: |\n          # Installation\n          ```bash\n          pip install your-package\n          ```\n\n      - path: quickstart.md\n        props:\n          title: Quick Start\n          weight: 30\n        content: |\n          # Quick Start\n          Your first project in 5 minutes.\n\n  - path: api/_index.md\n    props:\n      title: API Reference\n      weight: 30\n    content: |\n      # API Reference\n      Complete API documentation.\n```\n\n**Component Model:**\n- `path` — File or directory path\n- `type` — Component identity (blog, doc, landing)\n- `variant` — Visual style variant\n- `props` — Frontmatter data (title, weight, etc.)\n- `content` — Markdown body content\n- `pages` — Child components (makes this a section)\n- `cascade` — Values inherited by all descendants\n\n\u003c/details\u003e\n\n---\n\n## Features\n\n| Feature | Description | Docs |\n|---------|-------------|------|\n| **SEO \u0026 Discovery** | Sitemap, RSS, canonical URLs, Open Graph, social cards, search, JSON/LLM output, [llms.txt](https://llmstxt.org/), [Content Signals](https://contentsignals.org/) | [SEO \u0026 Discovery →](https://lbliii.github.io/bengal/docs/building/seo/) |\n| **Directives** | Tabs, admonitions, cards, dropdowns, code blocks | [Content →](https://lbliii.github.io/bengal/docs/content/) |\n| **Notebooks** | Native Jupyter `.ipynb` rendering, Binder/Colab links | [Notebooks →](https://lbliii.github.io/bengal/docs/content/authoring/notebooks/) |\n| **Autodoc** | Generate API docs from Python, CLI, OpenAPI | [Autodoc →](https://lbliii.github.io/bengal/docs/content/sources/autodoc/) |\n| **Remote Sources** | Pull content from GitHub, Notion, REST APIs | [Sources →](https://lbliii.github.io/bengal/docs/content/sources/) |\n| **Image Processing** | Resize, crop, format conversion (WebP/AVIF), srcset generation | [Images →](https://lbliii.github.io/bengal/docs/theming/templating/image-processing/) |\n| **Content Collections** | Type-safe frontmatter with dataclass/Pydantic schemas | [Collections →](https://lbliii.github.io/bengal/docs/content/collections/) |\n| **Theming** | Dark mode, responsive, syntax highlighting, search | [Theming →](https://lbliii.github.io/bengal/docs/theming/) |\n| **Validation** | Health checks, broken link detection, auto-fix | [Building →](https://lbliii.github.io/bengal/docs/building/) |\n| **Performance** | Parallel builds, incremental rebuilds, streaming | [Large Sites →](https://lbliii.github.io/bengal/docs/building/performance/large-sites/) |\n| **Zero-Config Deploy** | Auto-detects GitHub Pages, Netlify, Vercel | [Deployment →](https://lbliii.github.io/bengal/docs/building/deployment/) |\n\n📚 **Full documentation**: [lbliii.github.io/bengal](https://lbliii.github.io/bengal/)\n\n---\n\n## Configuration\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eSingle-file\u003c/strong\u003e — Simple projects\u003c/summary\u003e\n\n```toml\n# bengal.toml\n[site]\ntitle = \"My Site\"\nbaseurl = \"https://example.com\"\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eDirectory-based\u003c/strong\u003e — Multi-environment projects\u003c/summary\u003e\n\n```\nconfig/\n├── _default/           # Base configuration\n│   ├── site.yaml\n│   └── build.yaml\n├── environments/       # Environment overrides\n│   └── production.yaml\n└── profiles/           # Build profiles\n    └── dev.yaml\n```\n\n```bash\nbengal build -e production    # Production environment\nbengal build --profile dev    # Development profile\n```\n\n\u003c/details\u003e\n\n📖 **Configuration guide**: [Configuration →](https://lbliii.github.io/bengal/docs/building/configuration/)\n\n---\n\n## Project Structure\n\n```\nmysite/\n├── content/          # Markdown pages\n├── templates/        # Custom templates (optional)\n├── assets/           # Static files (CSS, JS, images)\n├── data/             # YAML/JSON data files\n├── config/           # Configuration directory\n└── public/           # Build output\n```\n\n---\n\n## Theming\n\nBengal ships with a modern, accessible default theme:\n\n- Dark mode with system preference detection\n- Responsive design with mobile navigation\n- Syntax highlighting with copy buttons\n- Table of contents with scroll spy\n- Full-text search (Lunr.js)\n\n**Customize templates:**\n\n```html\n{# templates/page.html #}\n{% extends \"base.html\" %}\n\n{% block content %}\n\u003carticle class=\"prose\"\u003e\n  \u003ch1\u003e{{ page.title }}\u003c/h1\u003e\n  {{ content | safe }}\n\u003c/article\u003e\n{% endblock %}\n```\n\n---\n\n## Pluggable Engines\n\nBengal follows a \"bring your own\" pattern — swap engines without changing your content.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eTemplate Engine\u003c/strong\u003e\u003c/summary\u003e\n\n| Engine | Description | Install |\n|--------|-------------|---------|\n| **Kida** | Bengal's native engine. AST-native, free-threading safe, Jinja2-compatible syntax | Built-in |\n\nKida is the built-in template engine. It uses Jinja2-compatible syntax, so existing Jinja2 templates generally work without changes. See the [Kida migration guide](https://lbliii.github.io/bengal/docs/theming/templating/kida/migration/from-jinja/) if migrating from Jinja2.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eMarkdown Parsers\u003c/strong\u003e\u003c/summary\u003e\n\n| Parser | Description | Install |\n|--------|-------------|---------|\n| **Patitas** (default) | Bengal's native parser. Typed AST, O(n) parsing, thread-safe | Built-in |\n| **Mistune** | Fast, modern parser | Built-in |\n| **Python-Markdown** | Full-featured, extensive extensions | Built-in |\n\n```yaml\n# config/_default/content.yaml\nmarkdown:\n  parser: patitas  # default, or mistune (legacy), python-markdown\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eSyntax Highlighters\u003c/strong\u003e\u003c/summary\u003e\n\n| Backend | Description | Install |\n|---------|-------------|---------|\n| **[Rosettes](https://github.com/lbliii/rosettes)** (default) | Lock-free, 55+ languages, O(n) guaranteed | `pip install rosettes` |\n\n```yaml\n# config/_default/theme.yaml\nhighlighting:\n  backend: rosettes\n```\n\nCustom backends can be registered via `register_backend()`.\n\n\u003c/details\u003e\n\n---\n\n## Requirements\n\n- **Python 3.14+** (uses free-threading and PEP 784 compression)\n- Linux, macOS, Windows\n\n---\n\n## Philosophy\n\nBengal prioritizes **correctness and clarity over backwards compatibility**.\n\nEach release represents the best solution we know how to deliver. When existing behavior no longer reflects the best design, it changes. Upgrades may require reading release notes and making adjustments.\n\n- **Fail loudly** — Breaking changes produce clear errors\n- **User control** — You choose when to upgrade; we choose what changes\n- **No hidden layers** — No compatibility shims or deprecated code paths\n\nIf you need multi-year stability, pin your version.\n\n---\n\n## Documentation\n\n📚 **[lbliii.github.io/bengal](https://lbliii.github.io/bengal/)**\n\n---\n\n## Development\n\n```bash\ngit clone https://github.com/lbliii/bengal.git\ncd bengal\nuv sync --group dev\npytest\n```\n\n**Multi-repo workspace:** With bengal, patitas, rosettes, etc. as siblings, copy `workspace-root.example/pyproject.toml` to the parent directory and run `uv sync` from there. The workspace root overrides sources so all packages use local versions. CI and end users (no workspace root) use PyPI.\n\n---\n\n## The Bengal Ecosystem\n\nA structured reactive stack — every layer written in pure Python for 3.14t free-threading.\n\n| | | | |\n|--:|---|---|---|\n| **ᓚᘏᗢ** | **Bengal** | Static site generator ← You are here | [Docs](https://lbliii.github.io/bengal/) |\n| **∿∿** | [Purr](https://github.com/lbliii/purr) | Content runtime | — |\n| **⌁⌁** | [Chirp](https://github.com/lbliii/chirp) | Web framework | [Docs](https://lbliii.github.io/chirp/) |\n| **=^..^=** | [Pounce](https://github.com/lbliii/pounce) | ASGI server | [Docs](https://lbliii.github.io/pounce/) |\n| **)彡** | [Kida](https://github.com/lbliii/kida) | Template engine | [Docs](https://lbliii.github.io/kida/) |\n| **ฅᨐฅ** | [Patitas](https://github.com/lbliii/patitas) | Markdown parser | [Docs](https://lbliii.github.io/patitas/) |\n| **⌾⌾⌾** | [Rosettes](https://github.com/lbliii/rosettes) | Syntax highlighter | [Docs](https://lbliii.github.io/rosettes/) |\n\nPython-native. Free-threading ready. No npm required.\n\n---\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flbliii%2Fbengal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flbliii%2Fbengal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flbliii%2Fbengal/lists"}