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

@@ -90,6 +90,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,50 @@
+# 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: ;
+:::
+```

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,53 @@
+// 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 override void FinalizeAndValidate(ParserContext context)
+	{
+		Caption = Prop("caption");
+
+		var separator = Prop("separator", "delimiter");
+		if (!string.IsNullOrEmpty(separator))
+			Separator = separator;
+
+		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))
+			Found = true;
+		else
+			this.EmitError($"CSV file `{CsvFilePath}` does not exist.");
+	}
+
+}

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,24 @@
+// 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
+
+
+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 = csvBlock.Found && !string.IsNullOrEmpty(csvBlock.CsvFilePath)
+			? CsvReader.ReadCsvFile(csvBlock.CsvFilePath, csvBlock.Separator, csvBlock.Build.ReadFileSystem)
+			: [];
+
+		return new CsvFileViewModel
+		{
+			DirectiveBlock = csvBlock,
+			CsvRows = rows
+		};
+	}
+}

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

@@ -0,0 +1,59 @@
+// 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.IO.Abstractions;
+using nietras.SeparatedValues;
+
+namespace Elastic.Markdown.Myst.Directives.CsvFile;
+
+public static class CsvReader
+{
+	public static List<string[]> ReadCsvFile(string filePath, string separator, IFileSystem? fileSystem = null)
+	{
+		var fs = fileSystem ?? new FileSystem();
+		return ReadWithSep(filePath, separator, fs);
+	}
+
+	private static List<string[]> ReadWithSep(string filePath, string separator, IFileSystem fileSystem)
+	{
+		var rows = new List<string[]>();
+		var separatorChar = separator == "," ? ',' : separator[0];
+		var spec = Sep.New(separatorChar);
+
+		// Sep works with actual file paths, not virtual file systems
+		// For testing with MockFileSystem, we'll read content first
+		if (fileSystem.GetType().Name == "MockFileSystem")
+		{
+			var content = fileSystem.File.ReadAllText(filePath);
+			using var reader = spec.Reader(o => o with { HasHeader = false, Unescape = true }).FromText(content);
+
+			foreach (var row in reader)
+			{
+				var rowData = new string[row.ColCount];
+				for (var i = 0; i < row.ColCount; i++)
+				{
+					rowData[i] = row[i].ToString();
+				}
+				rows.Add(rowData);
+			}
+		}
+		else
+		{
+			using var reader = spec.Reader(o => o with { HasHeader = false, Unescape = true }).FromFile(filePath);
+
+			foreach (var row in reader)
+			{
+				var rowData = new string[row.ColCount];
+				for (var i = 0; i < row.ColCount; i++)
+				{
+					rowData[i] = row[i].ToString();
+				}
+				rows.Add(rowData);
+			}
+		}
+
+		return rows;
+	}
+
+}

src/Elastic.Markdown/Myst/Directives/DirectiveBlockParser.cs

@@ -4,6 +4,7 @@
 
 using System.Collections.Frozen;
 using Elastic.Markdown.Myst.Directives.Admonition;
+using Elastic.Markdown.Myst.Directives.CsvFile;
 using Elastic.Markdown.Myst.Directives.Diagram;
 using Elastic.Markdown.Myst.Directives.Image;
 using Elastic.Markdown.Myst.Directives.Include;
@@ -44,7 +45,6 @@ public DirectiveBlockParser()
 	{
 		{ "bibliography", 5 },
 		{ "blockquote", 6 },
-		{ "csv-table", 9 },
 		{ "iframe", 14 },
 		{ "list-table", 17 },
 		{ "myst", 22 },
@@ -122,6 +122,9 @@ protected override DirectiveBlock CreateFencedBlock(BlockProcessor processor)
 		if (info.IndexOf("{settings}") > 0)
 			return new SettingsBlock(this, context);
 
+		if (info.IndexOf("{csv-file}") > 0)
+			return new CsvFileBlock(this, context);
+
 		foreach (var admonition in _admonitions)
 		{
 			if (info.IndexOf($"{{{admonition}}}") > 0)

src/Elastic.Markdown/Myst/Directives/DirectiveHtmlRenderer.cs

@@ -6,6 +6,7 @@
 using Elastic.Markdown.Diagnostics;
 using Elastic.Markdown.Myst.CodeBlocks;
 using Elastic.Markdown.Myst.Directives.Admonition;
+using Elastic.Markdown.Myst.Directives.CsvFile;
 using Elastic.Markdown.Myst.Directives.Diagram;
 using Elastic.Markdown.Myst.Directives.Dropdown;
 using Elastic.Markdown.Myst.Directives.Image;
@@ -81,6 +82,9 @@ protected override void Write(HtmlRenderer renderer, DirectiveBlock directiveBlo
 			case SettingsBlock settingsBlock:
 				WriteSettingsBlock(renderer, settingsBlock);
 				return;
+			case CsvFileBlock csvFileBlock:
+				WriteCsvFileBlock(renderer, csvFileBlock);
+				return;
 			case StepperBlock stepperBlock:
 				WriteStepperBlock(renderer, stepperBlock);
 				return;
@@ -407,4 +411,11 @@ void Render(Block o)
 				_ = renderer.Write($"(Block: {o.GetType().Name}");
 		}
 	}
+
+	private static void WriteCsvFileBlock(HtmlRenderer renderer, CsvFileBlock block)
+	{
+		var viewModel = CsvFileViewModel.Create(block);
+		var slice = CsvFileView.Create(viewModel);
+		RenderRazorSlice(slice, renderer);
+	}
 }