Add CSV file directive

Directory.Packages.props

@@ -56,6 +56,7 @@
     <PackageVersion Include="Proc" Version="0.9.1" />
     <PackageVersion Include="RazorSlices" Version="0.9.4" />
     <PackageVersion Include="Samboy063.Tomlet" Version="6.0.0" />
+    <PackageVersion Include="Sep" Version="0.11.0" />
     <PackageVersion Include="Slugify.Core" Version="4.0.1" />
     <PackageVersion Include="SoftCircuits.IniFileParser" Version="2.7.0" />
     <PackageVersion Include="System.IO.Abstractions" Version="22.0.15" />

docs/_docset.yml

@@ -96,6 +96,7 @@ toc:
       - file: code.md
       - file: comments.md
       - file: conditionals.md
+      - file: csv-file.md
       - hidden: diagrams.md
       - file: dropdowns.md
       - file: definition-lists.md

docs/_snippets/sample-data.csv

@@ -0,0 +1,6 @@
+Name,Age,City,Occupation
+John Doe,30,New York,Software Engineer
+Jane Smith,25,Los Angeles,Product Manager
+Bob Johnson,35,Chicago,Data Scientist
+Alice Brown,28,San Francisco,UX Designer
+Charlie Wilson,32,Boston,DevOps Engineer

docs/syntax/csv-file.md

@@ -0,0 +1,90 @@
+# CSV file directive
+
+The `{csv-file}` 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`.
+
+## Usage
+
+:::::{tab-set}
+
+::::{tab-item} Output
+
+:::{csv-file} ../_snippets/sample-data.csv
+:caption: Sample user data from the database
+:::
+
+::::
+
+::::{tab-item} Markdown
+
+```markdown
+:::{csv-file} _snippets/sample-data.csv
+:::
+```
+
+::::
+
+:::::
+
+## Options
+
+The CSV file directive supports several options to customize the table rendering:
+
+### Caption
+
+Add a descriptive caption above the table:
+
+```markdown
+:::{csv-file} _snippets/sample-data.csv
+:caption: Sample user data from the database
+:::
+```
+
+### Custom separator
+
+Specify a custom field separator (default is comma):
+
+```markdown
+:::{csv-file} _snippets/sample-data.csv
+:separator: ;
+:::
+```
+
+### Size and performance limits
+
+Control how much data is loaded and displayed:
+
+```markdown
+:::{csv-file} _snippets/large-dataset.csv
+:max-rows: 5000
+:max-columns: 50
+:max-size: 20MB
+:::
+```
+
+- **max-rows**: Maximum number of rows to display (default: 10,000)
+- **max-columns**: Maximum number of columns to display (default: 100)  
+- **max-size**: Maximum file size to process (default: 10MB). Supports KB, MB, GB units.
+
+### Preview mode
+
+For very large files, enable preview mode to show only the first 100 rows:
+
+```markdown
+:::{csv-file} _snippets/huge-dataset.csv
+:preview-only: true
+:::
+```
+
+## Performance considerations
+
+The CSV directive is optimized for large files:
+
+- Files are processed using streaming to avoid loading everything into memory
+- Size validation prevents processing of files that exceed the specified limits
+- 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:
+- Setting appropriate `max-rows` and `max-columns` limits
+- Using `preview-only: true` for exploratory data viewing
+- Increasing `max-size` only when necessary

docs/syntax/index.md

@@ -12,6 +12,23 @@ V3 fully supports [CommonMark](https://commonmark.org/), a strongly defined, sta
 * [Directives](#directives)
 * [GitHub-flavored markdown](#github-flavored-markdown)
 
+## Available directives
+
+The following directives are available in Elastic Docs V3:
+
+* [Admonitions](admonitions.md) - Callouts and warnings
+* [Code blocks](code.md) - Syntax-highlighted code
+* [CSV file](csv-file.md) - Render CSV files as tables
+* [Diagrams](diagrams.md) - Visual diagrams and charts
+* [Dropdowns](dropdowns.md) - Collapsible content
+* [Images](images.md) - Enhanced image handling
+* [Include](file_inclusion.md) - Include content from other files
+* [Settings](automated_settings.md) - Configuration blocks
+* [Stepper](stepper.md) - Step-by-step content
+* [Tabs](tabs.md) - Tabbed content organization
+* [Tables](tables.md) - Data tables
+* [Version blocks](version-variables.md) - API version information
+
 ## Directives
 
 Directives extend CommonMark functionality. Directives have the following syntax:

src/Elastic.Markdown/Elastic.Markdown.csproj

@@ -20,6 +20,7 @@
     <PackageReference Include="Markdig" />
     <PackageReference Include="Microsoft.Extensions.Logging" />
     <PackageReference Include="RazorSlices" />
+    <PackageReference Include="Sep" />
     <PackageReference Include="Slugify.Core" />
     <PackageReference Include="Utf8StreamReader" />
     <PackageReference Include="Vecc.YamlDotNet.Analyzers.StaticGenerator" />

src/Elastic.Markdown/Myst/Directives/CsvFile/CsvFileBlock.cs

@@ -0,0 +1,129 @@
+// Licensed to Elasticsearch B.V under one or more agreements.
+// Elasticsearch B.V licenses this file to you under the Apache 2.0 License.
+// See the LICENSE file in the project root for more information
+
+using System.Globalization;
+using System.IO.Abstractions;
+using Elastic.Markdown.Diagnostics;
+
+namespace Elastic.Markdown.Myst.Directives.CsvFile;
+
+public class CsvFileBlock(DirectiveBlockParser parser, ParserContext context) : DirectiveBlock(parser, context)
+{
+	public override string Directive => "csv-file";
+
+	public string? CsvFilePath { get; private set; }
+	public string? CsvFilePathRelativeToSource { get; private set; }
+	public bool Found { get; private set; }
+	public string? Caption { get; private set; }
+	public string Separator { get; private set; } = ",";
+	public int MaxRows { get; private set; } = 10000;
+	public long MaxFileSizeBytes { get; private set; } = 10 * 1024 * 1024; // 10MB
+	public int MaxColumns { get; private set; } = 100;
+	public bool PreviewOnly { get; private set; }
+
+	public override void FinalizeAndValidate(ParserContext context)
+	{
+		Caption = Prop("caption");
+
+		var separator = Prop("separator", "delimiter");
+		if (!string.IsNullOrEmpty(separator))
+			Separator = separator;
+
+		if (int.TryParse(Prop("max-rows"), out var maxRows) && maxRows > 0)
+			MaxRows = maxRows;
+
+		if (ParseFileSize(Prop("max-size"), out var maxSize) && maxSize > 0)
+			MaxFileSizeBytes = maxSize;
+
+		if (int.TryParse(Prop("max-columns"), out var maxColumns) && maxColumns > 0)
+			MaxColumns = maxColumns;
+
+		PreviewOnly = bool.TryParse(Prop("preview-only"), out var preview) && preview;
+
+		ExtractCsvPath(context);
+	}
+
+	private void ExtractCsvPath(ParserContext context)
+	{
+		var csvPath = Arguments;
+		if (string.IsNullOrWhiteSpace(csvPath))
+		{
+			this.EmitError("csv-file requires an argument specifying the path to the CSV file.");
+			return;
+		}
+
+		var csvFrom = context.MarkdownSourcePath.Directory!.FullName;
+		if (csvPath.StartsWith('/'))
+			csvFrom = Build.DocumentationSourceDirectory.FullName;
+
+		CsvFilePath = Path.Combine(csvFrom, csvPath.TrimStart('/'));
+		CsvFilePathRelativeToSource = Path.GetRelativePath(Build.DocumentationSourceDirectory.FullName, CsvFilePath);
+
+		if (Build.ReadFileSystem.File.Exists(CsvFilePath))
+		{
+			ValidateFileSize();
+			Found = true;
+		}
+		else
+			this.EmitError($"CSV file `{CsvFilePath}` does not exist.");
+	}
+
+	private void ValidateFileSize()
+	{
+		if (CsvFilePath == null)
+			return;
+
+		try
+		{
+			var fileInfo = Build.ReadFileSystem.FileInfo.New(CsvFilePath);
+			if (fileInfo.Length > MaxFileSizeBytes)
+			{
+				var sizeMB = fileInfo.Length / (1024.0 * 1024.0);
+				var maxSizeMB = MaxFileSizeBytes / (1024.0 * 1024.0);
+				this.EmitError($"CSV file `{CsvFilePath}` is {sizeMB:F1}MB, which exceeds the maximum allowed size of {maxSizeMB:F1}MB. Use :max-size to increase the limit.");
+				Found = false;
+			}
+		}
+		catch (Exception ex)
+		{
+			this.EmitError($"Could not validate CSV file size: {ex.Message}");
+			Found = false;
+		}
+	}
+
+	private static bool ParseFileSize(string? sizeString, out long bytes)
+	{
+		bytes = 0;
+		if (string.IsNullOrEmpty(sizeString))
+			return false;
+
+		var multiplier = 1L;
+		var value = sizeString.ToUpperInvariant();
+
+		if (value.EndsWith("KB"))
+		{
+			multiplier = 1024;
+			value = value[..^2];
+		}
+		else if (value.EndsWith("MB"))
+		{
+			multiplier = 1024 * 1024;
+			value = value[..^2];
+		}
+		else if (value.EndsWith("GB"))
+		{
+			multiplier = 1024 * 1024 * 1024;
+			value = value[..^2];
+		}
+
+		if (double.TryParse(value, out var numericValue))
+		{
+			bytes = (long)(numericValue * multiplier);
+			return true;
+		}
+
+		return false;
+	}
+
+}

src/Elastic.Markdown/Myst/Directives/CsvFile/CsvFileView.cshtml

@@ -0,0 +1,40 @@
+@using Elastic.Markdown.Myst.Directives.CsvFile
+@inherits RazorSlice<CsvFileViewModel>
+
+@{
+    var csvBlock = (CsvFileBlock)Model.DirectiveBlock;
+    if (!csvBlock.Found || Model.CsvRows.Count == 0)
+    {
+        return;
+    }
+}
+
+<div class="table-wrapper">
+    @if (!string.IsNullOrEmpty(csvBlock.Caption))
+    {
+        <caption>@csvBlock.Caption</caption>
+    }
+
+    <table>
+        <thead>
+            <tr>
+                @for (var i = 0; i < Model.CsvRows[0].Length; i++)
+                {
+                    <th>@Model.CsvRows[0][i]</th>
+                }
+            </tr>
+        </thead>
+
+        <tbody>
+            @for (var rowIndex = 1; rowIndex < Model.CsvRows.Count; rowIndex++)
+            {
+                <tr>
+                    @for (var i = 0; i < Model.CsvRows[rowIndex].Length; i++)
+                    {
+                        <td>@Model.CsvRows[rowIndex][i]</td>
+                    }
+                </tr>
+            }
+        </tbody>
+    </table>
+</div>

src/Elastic.Markdown/Myst/Directives/CsvFile/CsvFileViewModel.cs

@@ -0,0 +1,64 @@
+// Licensed to Elasticsearch B.V under one or more agreements.
+// Elasticsearch B.V licenses this file to you under the Apache 2.0 License.
+// See the LICENSE file in the project root for more information
+
+using Elastic.Markdown.Diagnostics;
+
+namespace Elastic.Markdown.Myst.Directives.CsvFile;
+
+public class CsvFileViewModel : DirectiveViewModel
+{
+	public required List<string[]> CsvRows { get; init; }
+
+	public static CsvFileViewModel Create(CsvFileBlock csvBlock)
+	{
+		var rows = new List<string[]>();
+
+		if (csvBlock.Found && !string.IsNullOrEmpty(csvBlock.CsvFilePath))
+		{
+			var csvData = CsvReader.ReadCsvFile(csvBlock.CsvFilePath, csvBlock.Separator, csvBlock.Build.ReadFileSystem);
+			var rowCount = 0;
+			var columnCountExceeded = false;
+
+			foreach (var row in csvData)
+			{
+				if (rowCount >= csvBlock.MaxRows)
+				{
+					csvBlock.EmitWarning($"CSV file contains more than {csvBlock.MaxRows} rows. Only the first {csvBlock.MaxRows} rows will be displayed. Use :max-rows to increase the limit.");
+					break;
+				}
+
+				if (row.Length > csvBlock.MaxColumns)
+				{
+					if (!columnCountExceeded)
+					{
+						csvBlock.EmitWarning($"CSV file contains more than {csvBlock.MaxColumns} columns. Only the first {csvBlock.MaxColumns} columns will be displayed. Use :max-columns to increase the limit.");
+						columnCountExceeded = true;
+					}
+
+					var trimmedRow = new string[csvBlock.MaxColumns];
+					Array.Copy(row, trimmedRow, csvBlock.MaxColumns);
+					rows.Add(trimmedRow);
+				}
+				else
+				{
+					rows.Add(row);
+				}
+
+				rowCount++;
+			}
+
+			if (csvBlock.PreviewOnly && rowCount > 100)
+			{
+				csvBlock.EmitWarning("Preview mode is enabled. Showing first 100 rows of CSV data.");
+				rows = rows.Take(100).ToList();
+			}
+		}
+
+		return new CsvFileViewModel
+		{
+			DirectiveBlock = csvBlock,
+			CsvRows = rows
+		};
+	}
+}