# External References URL: /docs/content/authoring/external-references/ Section: authoring Tags: linking, cross-references, intersphinx, external -------------------------------------------------------------------------------- External References Bengal's external references feature lets you create rich links to external documentation—Python stdlib, NumPy, other Bengal sites—using the familiar [[link]] syntax. Similar to Sphinx's intersphinx, but with an offline-first design and graceful fallback. Quick Reference Syntax Resolution Example [[ext:project:target]] URL template or index [[ext:python:pathlib.Path]] [[ext:project:target|text]] With custom text [[ext:numpy:ndarray|NumPy Arrays]] {{ ext('project', 'target') }} Template function {{ ext('python', 'str.split') }} Syntax External references use the ext: prefix followed by project and target: [[ext:project:target]] [[ext:project:target|Custom Link Text]] Components: ext: — Prefix indicating external reference project — Project name (configured in external_refs.yaml) target — Target identifier (class, function, module, page path) Examples Python Standard Library See [[ext:python:pathlib.Path]] for filesystem operations. The [[ext:python:typing.TypedDict|TypedDict class]] enables typed dictionaries. Check [[ext:python:json.dumps]] for JSON serialization. Third-Party Libraries Use [[ext:numpy:ndarray]] for efficient array operations. The [[ext:requests:Session|requests Session]] handles connection pooling. See [[ext:pydantic:BaseModel]] for data validation. Bengal Ecosystem Link to other Bengal-powered documentation sites: Bengal uses [[ext:kida:Markup]] for safe HTML rendering. Syntax highlighting is powered by [[ext:rosettes:PythonLexer]]. Resolution Strategy Bengal resolves external references using a three-tier strategy: Tier 1: URL Templates (Instant, Offline) For well-known projects, Bengal uses URL templates that resolve instantly without network access: # external_refs.yaml external_refs: templates: python: "https://docs.python.org/3/library/{module}.html#{name}" numpy: "https://numpy.org/doc/stable/reference/generated/numpy.{name}.html" requests: "https://requests.readthedocs.io/en/latest/api/#{name}" Template variables: Variable Description Example {name} Full target name pathlib.Path {name_lower} Lowercase target pathlib.path {module} Module portion pathlib {class} Class portion Path {function} Function portion exists Tier 2: Bengal Indexes (Rich Metadata) For Bengal ecosystem sites, fetch and cache xref.json indexes: # external_refs.yaml external_refs: indexes: - name: "kida" url: "https://lbliii.github.io/kida/xref.json" cache_days: 7 - name: "rosettes" url: "https://lbliii.github.io/rosettes/xref.json" cache_days: 7 Bengal indexes provide: Page titles for automatic link text Type information (class, function, module, page) Summaries for tooltips Accurate URLs Tier 3: Graceful Fallback If resolution fails, Bengal renders the reference as inline code with a warning—builds never break: <code class="extref extref-unresolved">ext:unknown:Target</code> A warning is logged during build: warning: unresolved_external_ref ref=ext:unknown:Target Configuration Configure external references in config/_default/external_refs.yaml: external_refs: # Enable/disable the feature enabled: true # Export xref.json for other sites to consume export_index: true # Cache directory for fetched indexes cache_dir: ".bengal/cache/external_refs" # Default cache duration default_cache_days: 7 # URL templates (Tier 1) - instant, offline resolution templates: python: "https://docs.python.org/3/library/{module}.html#{name}" typing: "https://docs.python.org/3/library/typing.html#{name}" numpy: "https://numpy.org/doc/stable/reference/generated/numpy.{name}.html" pandas: "https://pandas.pydata.org/docs/reference/api/pandas.{name}.html" requests: "https://requests.readthedocs.io/en/latest/api/#{name}" httpx: "https://www.python-httpx.org/api/#{name_lower}" fastapi: "https://fastapi.tiangolo.com/reference/{module}/#{name}" pydantic: "https://docs.pydantic.dev/latest/api/{module}/#{name}" # Bengal ecosystem indexes (Tier 2) - rich metadata indexes: - name: "kida" url: "https://lbliii.github.io/kida/xref.json" cache_days: 7 - name: "rosettes" url: "https://lbliii.github.io/rosettes/xref.json" cache_days: 7 Configuration Options Option Type Default Description enabled bool true Enable external references export_index bool false Generate xref.json for your site cache_dir string .bengal/cache/external_refs Where to cache fetched indexes default_cache_days int 7 How long to cache indexes templates dict (built-in) URL templates for common projects indexes list [] Bengal indexes to fetch Template Functions Use external references in templates with these functions: ext(project, target, text=None) Generate an external reference link: {{ ext('python', 'pathlib.Path') }} {{ ext('python', 'pathlib.Path', 'Path class') }} {{ ext('kida', 'Markup') }} Returns: Safe HTML link ext_exists(project, target) Check if an external reference is resolvable: {% if ext_exists('kida', 'Markup') %} See {{ ext('kida', 'Markup') }} for safe HTML. {% else %} See the Kida documentation for Markup. {% end %} Returns: true if resolvable, false otherwise Exporting Your Site's Index Enable export_index to generate xref.json for your site: external_refs: export_index: true Bengal generates public/xref.json containing: { "version": 1, "generator": "bengal", "generated_at": "2026-01-10T12:00:00Z", "base_url": "https://mysite.dev", "entries": [ { "id": "MyClass", "type": "class", "path": "/docs/api/myclass/", "title": "MyClass", "summary": "A useful class for doing things." }, { "id": "docs/getting-started", "type": "page", "path": "/docs/getting-started/", "title": "Getting Started", "summary": "Quick start guide for new users." } ] } Other Bengal sites can then link to your documentation: # On another site external_refs: indexes: - name: "myproject" url: "https://mysite.dev/xref.json" See [[ext:myproject:MyClass]] for details. Use Cases API Documentation Link to standard library and third-party APIs: ## HTTP Client The client uses [[ext:httpx:AsyncClient]] for async requests. Results are validated with [[ext:pydantic:BaseModel]]. For synchronous code, use [[ext:requests:Session]] instead. Migration Guides Reference external documentation when migrating: ## Migrating from Requests to HTTPX Replace [[ext:requests:Session]] with [[ext:httpx:Client]]: **Before:** ```python import requests session = requests.Session() After: import httpx client = httpx.Client() ### Cross-Project Documentation Link between your own projects: ```markdown ## Architecture Bengal's rendering pipeline uses: - [[ext:kida:Markup]] for HTML safety - [[ext:rosettes:PythonLexer]] for syntax highlighting - [[ext:patitas:MistuneFork]] for Markdown parsing Comparison with Intersphinx Feature Bengal External Refs Sphinx Intersphinx Syntax [[ext:project:target]] :py:class:\project.Target`` Offline support ✅ URL templates ❌ Requires inventory Build failure on missing ❌ Graceful fallback ✅ Can fail Index format JSON (xref.json) Binary (objects.inv) Configuration YAML conf.py Tips Use URL Templates for Stability URL templates (Tier 1) are more reliable than fetched indexes: Work offline No network latency No cache staleness issues Configure templates for frequently-referenced projects. Cache Indexes Appropriately For actively-developed projects, use shorter cache times: indexes: - name: "myproject" url: "https://myproject.dev/xref.json" cache_days: 1 # Frequent updates For stable projects, longer cache times reduce network calls: indexes: - name: "stable-lib" url: "https://stable-lib.dev/xref.json" cache_days: 30 # Stable API Don't Overuse External references are powerful but can clutter content. Use them for: API class/function references Standard library documentation Cross-project links in ecosystem docs For general external links, standard Markdown links are clearer: <!-- Good: API reference --> See [[ext:python:pathlib.Path]] for path operations. <!-- Better as regular link: general resource --> See [Python's pathlib tutorial](https://docs.python.org/3/library/pathlib.html) for an introduction. Troubleshooting Unresolved References If a reference shows as unresolved: Check project name — Must match configured template or index name Check target format — Use the format expected by that project Check cache — Clear .bengal/cache/external_refs/ and rebuild Check network — Index fetching requires network access Template Not Matching If URL templates produce wrong URLs: Check variable names — Use {name}, {module}, {class}, {function} Check URL format — Compare with actual documentation URLs Test manually — Build and verify generated links Index Fetch Failures If Bengal can't fetch an index: Check URL — Ensure the xref.json URL is correct Check network — Verify network access during build Check permissions — Some indexes may require authentication indexes: - name: "private-project" url: "https://internal.example.com/xref.json" auth_header: "Bearer ${DOCS_TOKEN}" # Environment variable See Also Linking Guide — All linking methods Cross-Version Links — Link between versions Template Functions — ext() and ext_exists() -------------------------------------------------------------------------------- Metadata: - Author: lbliii - Word Count: 1022 - Reading Time: 5 minutes