CSV files

The {csv-include} directive allows you to include and render CSV files as formatted tables in your documentation. The directive automatically parses CSV content and renders it using the standard table styles defined in table.css.

:::{csv-include} _snippets/sample-data.csv
:::
		

The CSV file directive supports several options to customize the table rendering:

Add a descriptive caption above the table:

:::{csv-include} _snippets/sample-data.csv
:caption: Sample user data from the database
:::
		

Specify a custom field separator (default is comma):

:::{csv-include} _snippets/sample-data.csv
:separator: ;
:::
		

CSV files with many columns are rendered as scrollable tables:

:::{csv-include} _snippets/sample-data-12-columns.csv
:caption: Product inventory with 12 columns
:::
		

The directive includes built-in performance limits to handle large files efficiently:

• Row limit: Maximum of 25,000 rows will be displayed
• Column limit: Maximum of 15 columns will be displayed
• File size limit: Maximum file size of 10MB

The CSV directive is optimized for large files:

• Files are processed using streaming to avoid loading everything into memory
• Built-in size validation prevents processing of files that exceed 10MB
• Row and column limits protect against accidentally rendering massive tables
• Warning messages are displayed when limits are exceeded

For optimal performance with large CSV files, consider:

• Breaking very large files into smaller, more manageable chunks