---
layout: community_extension_doc
title: Documentation
---

## Submit a Community Extension

Community Extensions must be public, open-source, and hosted on GitHub.
Users of such extensions are encouraged to check the relevant extension repository for giving feedback, to look at the implementation, and to report issues.

To submit a Community Extension, please open a pull request to the [Community Extensions Repository](https://github.com/duckdb/community-extensions) with a single `description.yml` file in the folder `extensions/⟨name_of_the_extension⟩`{:.language-sql .highlight}.

### YAML Descriptor

The structure of the YAML descriptor is as follows:

| Field | Description |
|--|--|
| `extension.name` | Name of the extension. Extension names are case-insensitive, so only lowercase letters, numbers and `-` or `_` are allowed |
| `extension.description` | Short description of the extension |
| `extension.version` | Semantic versioning of the extension |
| `extension.language` | `C++`, `Rust & C++`, `C++ & SQL`, or whatever combination of languages the extension code relies on |
| `extension.build` | Build system the extension uses, at the moment only `cmake` is supported |
| `extension.license` | License that applies to the extension |
| `extension.maintainers` | A list of maintainers for the extension |
| `extension.excluded_platforms` | Optional, allows specifying whether certain platforms are not supported |
| `extension.requires_toolchains` | Optional, allows specifying whether additional build-time dependencies are required |
| `repo.github` | Organization name '/' Repository name of the GitHub-hosted public repository |
| `repo.ref` | Git ref for the extension |

These fields are used to build, test and deploy the extension, and might also be reflected in the documentation.

Extension maintainers are encouraged to provide two optional fields in the descriptor, to be only used in the autogenerated documentation:

| Field | Description |
|--|--|
| `docs.hello_world` | A `Hello, World!` code snippet, i.e., a self-contained example of an extension's capabilities |
| `docs.extended_description` | Extra context on the extension, relevant links, or a tour of the extension's capabilities |

### Hosted Extension Documentation Page

Each Community Extension has a documentation page at `https://duckdb.org/community_extensions/extensions/⟨extension_name⟩`{:.language-sql .highlight}. For example, this is the page for [h3]({% link community_extensions/extensions/h3.md %}).

Documentation pages are generated from the fields provided in the YAML descriptor file that is part of the [Community Extensions Repository](https://github.com/duckdb/community-extensions) and from the auto-detected changes that a given extension introduces in DuckDB.

The process is roughly as follows:

```sql
CREATE TABLE functions_pre AS SELECT ... FROM duckdb_functions();
LOAD extension_name;
CREATE TABLE functions_post AS SELECT ... FROM duckdb_functions();
SELECT * FROM functions_post EXCEPT (FROM functions_pre) ORDER BY ...;
```

This works well for detecting new functions, function overloads, new settings, and new types.

Detection of other changes to the system (e.g., whether an additional parser or optimizer callback has been registered) is viable, but not yet implemented. Those are recommended to be provided as part of the `docs.extended_description` field.

### List of Extensions

All the available community extensions are listed in the [“List of Community Extensions”]({% link community_extensions/list_of_extensions.md %}) page.