CSV to AsciiDoc Table Converter

A CSV to AsciiDoc converter turns a spreadsheet into a table asciidoctor and Antora will render. This one writes a real cols specification carrying an alignment per column rather than a bare count, escapes the pipe and nothing else so intentional markup still works, and gives you the block id, title, frame and grid controls the format actually has. Nothing is uploaded.

Need to trim or reorder columns first? Open the app

cols is not a column count

Most generated AsciiDoc tables carry cols="5", which tells asciidoctor there are five columns and nothing else. It works, and it throws away the most useful attribute the format has.

A cols entry can carry three things. A horizontal alignment: < left, ^ centre, > right. A width multiple, so 2 makes a column twice as wide as a 1. And a style letter that changes how the cell's content is interpreted: a for a cell that is itself AsciiDoc with its own lists and paragraphs, l for literal, m for monospace, h for header-styled.

This writes an entry per column with the alignment set from the column's detected type, so numbers are right aligned and the digits line up:

[cols="<1,<1,>1,<1",options="header"]

Types are decided once per column by reading the whole column, so a price column mixing 4.25 and 6.80 stays text and left aligned rather than half one way. If the automatic choice is wrong for your table, you can force everything left, centre or right.

A worked example

Three products, one with a pipe in a cell:

sku,name,qty,note
00412,Bracket 40mm,1420,in stock
01730,Bronze bushing,3105,"low | reorder"
04510,Spur gear,410,in stock

With a title and a block id:

[[stock-table]]
.Current stock
[cols="<1,<1,>1,<1",options="header"]
|===
|sku
|name
|qty
|note

|00412
|Bracket 40mm
|1420
|in stock

|01730
|Bronze bushing
|3105
|low \| reorder

|04510
|Spur gear
|410
|in stock
|===

The qty column got >1 because it typed as numeric. The pipe in the note is escaped as \|, which is the one escape AsciiDoc tables need. The anchor above the title means <<stock-table>> elsewhere in the document links here.

The ordering of those first three lines is fixed by the format and easy to get wrong by hand: the anchor comes first, then the block title starting with a dot, then the attribute list in square brackets, then the |=== delimiter. Swap any two and asciidoctor reads one of them as a paragraph.

Escaping only what has to be escaped

Exactly one character is escaped: the pipe, because a pipe begins a cell and a raw one inside a value splits the row. Everything else is left as it is, and that is a deliberate choice rather than an oversight.

Cell content in AsciiDoc is AsciiDoc. A value of *total* renders bold, `code` renders as monospace, and a URL becomes a link. If you are writing documentation, that is very often what you want, and a converter that escaped it would be actively unhelpful.

When it is not what you want, the format has a proper answer: set the column's style to l in the cols spec and asciidoctor treats that column's content as literal text. That is a one-character edit on the line the converter already wrote for you, and it is mentioned in the warnings so the option is visible.

Line breaks inside a cell become spaces, with a count, since a raw newline in the middle of a cell ends it.

Frame and grid are the other two controls worth knowing. frame=topbot with grid=rows gives you horizontal rules only, no vertical lines and no box, which is the same visual argument booktabs makes for LaTeX and suits most documentation themes. %autowidth shrinks the table to its content instead of stretching it to the full page width, which matters for a narrow table in a wide theme.

Questions

What is the cols attribute actually for?

Far more than counting columns. Each entry can carry a horizontal alignment, a width multiple, and a style letter: a for a cell whose content is itself AsciiDoc, l for literal, m for monospace, h for header-styled. Emitting a bare cols=5 throws all of that away and gives you a table where a column of figures is left aligned. This writes an entry per column with the alignment set from the column's type.

Which characters are escaped?

Only the pipe, as a backslash-pipe. That is the one character that ends a cell. Everything else is left alone on purpose: a value like *total* really should render as bold, because the content is AsciiDoc and escaping it would surprise anyone who put the markup there deliberately. If your data holds markup you want shown literally, set the column style to l in the cols spec.

How do I make the table referenceable?

Give it a block id and it comes out as a double-bracketed anchor above the table, so a cross-reference elsewhere in the document can point at it. The block title, written as a line beginning with a dot, becomes the table's caption. The order matters and is handled for you: anchor first, then title, then the attribute list, then the table delimiters.

What do frame and grid do?

Frame controls the border around the outside of the table: all, topbot, sides or none. Grid controls the internal rules: all, rows, cols or none. A frame of topbot with a grid of rows gives you the clean horizontal-rules-only look that most documentation themes suit, and it is the AsciiDoc equivalent of what booktabs does for LaTeX.

Why is each cell on its own line?

Because that is the shape asciidoctor's own documentation uses, and it makes a diff readable: changing one cell touches one line. The blank line after the header block is a convention that makes the header visually obvious in the source. There is a compact option that puts a whole row on one line if you prefer denser source.

What happens if I turn the header option off?

The first row is written as ordinary data and the rendered table has no header styling and no th elements. You are told so in the warnings, because a table that looks headerless in the output when you expected a header is otherwise a puzzle. Leave it on unless your first row genuinely is data.

Is anything uploaded?

No. Everything runs in your browser tab, nothing is sent to a server, nothing is kept between visits and there is no row cap. Paste the block straight into your .adoc file and asciidoctor or Antora will render it.

Convert your CSV to AsciiDoc

No sign-up, no upload, no row cap. A real cols spec, per-column alignment, and only the pipe escaped.

Back to the converter