Add DataFrame.renderToMarkdown(): String function by koperagen · Pull Request #1760 · Kotlin/dataframe

koperagen · 2026-03-18T18:13:24Z

fixes #525
First, i added more tests on original renderToString. Then a little refactoring to extract common logic. +new function

Original rendering has some quirks that can be seen in test asserts. For now i just preserved it as is, but probably let's improve it as well - it will be more obvious with new tests

Fixes #525

Jolanrensen · 2026-03-20T14:20:38Z

Original rendering has some quirks that can be seen in test asserts

What kind of quirks do you mean?

core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/io/string.kt

Jolanrensen · 2026-03-20T14:42:42Z

core/src/test/kotlin/org/jetbrains/kotlinx/dataframe/rendering/RenderToMarkdownTests.kt

+        val expected =
+            """
+            |  | name | age | city |
+            |---:|---:|---:|---:|


what do these colons do? I don't think I've seen them before in MD tables

ah! it's alignment, right? Uhm, maybe we should have "no alignment" as an option, as well as right/left alignment. There are some right-to-left languages that could cause issues with a default alignment. (Actually, they probably already break tables like these, they broke our toString() very much too)

could we still have a "no-alignment" option?

sure! it's still in progress, i'll update once more after review

core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/io/string.kt

Jolanrensen · 2026-03-20T14:51:31Z

core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/io/string.kt

+        val decimalFormat =
+            if (precision >= 0) RendererDecimalFormat.fromPrecision(precision) else RendererDecimalFormat.of("%e")
+        top.values().map {
+            escapeValue(renderValueForStdout(it, valueLimit, decimalFormat = decimalFormat).truncatedContent)


maybe create a new issue for exploring rendering nested frames as <details> like toStaticHtml? or at least mention this option in some kdoc :) Speaking of... small kdoc please? :))

koperagen · 2026-03-30T17:18:54Z

@Jolanrensen please have a look when you have time. I checked default print output on a 7500 rows x 77 columns "real world data" output and from there made a bunch of changes. One important is always printing column types and on a separate line, which i think makes a lot of sense for String API ease of use / dataschema declarations.
Went to compare with pandas outputs and stumbled upon this https://pypi.org/project/tabulate/. Thought we could have a few styles as well

Jolanrensen · 2026-03-31T15:19:03Z

Wow awesome!

One important is always printing column types and on a separate line, which i think makes a lot of sense for String API ease of use / dataschema declarations.

I agree, especially with large columnGroup/frameColumn types!

Small concern about this approach though with columnTypes = true, borders = false, rowIndex = false as it becomes quite hard to differentiate between the name/type/values.

     name  age    city
   String  Int  String
    Alice   30  Berlin
      Bob   25   Paris
  Charlie   35  London

I wonder how other libraries solve this. Maybe we could mark our types somehow too? Something like

     name   age     city
  `String` `Int` `String`
    Alice    30   Berlin
      Bob    25    Paris
  Charlie    35   London

or

     name   age     city
  String<  Int<  String<
    Alice    30   Berlin
      Bob    25    Paris
  Charlie    35   London

Okay, my examples are quite ugly, but you get the idea

koperagen · 2026-03-31T15:23:44Z

Wow awesome!

One important is always printing column types and on a separate line, which i think makes a lot of sense for String API ease of use / dataschema declarations.

I agree, especially with large columnGroup/frameColumn types!

Small concern about this approach though with columnTypes = true, borders = false, rowIndex = false as it becomes quite hard to differentiate between the name/type/values.
     name  age    city
   String  Int  String
    Alice   30  Berlin
      Bob   25   Paris
  Charlie   35  London
I wonder how other libraries solve this. Maybe we could mark our types somehow too? Something like
     name   age     city
  `String` `Int` `String`
    Alice    30   Berlin
      Bob    25    Paris
  Charlie    35   London
or
     name   age     city
  String<  Int<  String<
    Alice    30   Berlin
      Bob    25    Paris
  Charlie    35   London
Okay, my examples are quite ugly, but you get the idea

Without index = true it's indeed a bit confusing
I was looking at R https://dplyr.tidyverse.org/.

pandas simply doesn't render types in print, looks like they instead provide "info" akin to our "describe". Maybe backticks are good option for us. Should we wrap always or only when index = false?

Jolanrensen · 2026-03-31T19:02:44Z

core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/io/string.kt

 ): String {
    val sb = StringBuilder()
+    val table = prepareTable(rowsLimit, valueLimit, columnTypes, rowIndex)
+    val columnLengths = table.values.mapIndexed { col, vals ->


wait... so this is the... width... of each column in number of characters?

Jolanrensen · 2026-03-31T19:07:42Z

core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/io/string.kt

+    rowIndex: Boolean = true,
+): String = renderToString(rowsLimit, valueLimit, borders, alignLeft, columnTypes, title, rowIndex)
+
+public interface StringBorderRenderingStyle {


I think you could drop the "Rendering" part. "StringBorderStyle" is already clear enough (probably "BorderStyle" too if we think it doesn't clutter the rest of the library too much)

Jolanrensen · 2026-03-31T19:09:27Z

     name    age      city
 <String>  <Int>  <String>
    Alice     30    Berlin
      Bob     25     Paris
  Charlie     35    London

Oh the R brackets may also work :) I think I like them better (probably because I'm used to seeing types inside <> in Kotlin too :D)

compared to:

     name    age      city
 `String`  `Int`  `String`
    Alice     30    Berlin
      Bob     25     Paris
  Charlie     35    London

As for when we should wrap them, I think we should just always do it. We had : before to signify we were displaying a type instead of a column name. So I think it would help to have it always:

???????????????????????????????????
?   ?      name?    age?      city?
?   ?  <String>?  <Int>?  <String>?
???????????????????????????????????
?  0?     Alice?     30?    Berlin?
?  1?       Bob?     25?     Paris?
?  2?   Charlie?     35?    London?
???????????????????????????????????

         name    age      city
     <String>  <Int>  <String>
  0     Alice     30    Berlin
  1       Bob     25     Paris
  2   Charlie     35    London

May be a bit overboard for frameColumns, but it is still quite clear we're talking about types:

            a                                     group
     <Double>  <[a:Double, group:{l:Double, r:Double}]>
  0       0.0  [1 x 2] { a:0.000000, group:{ l:0.000...

Jolanrensen · 2026-03-31T19:21:20Z

btw, what about markdown? can we / should we also display the type on a new line? Does md even support mutliple-lines in headers?

Edit:

	name <String>	age <Int>	city <String>
0	Alice	30	Berlin
1	Bob	25	Paris
2	Charlie	35	London

 |  | name<br>\<String\> | age<br>\<Int\> | city<br>\<String\> |
 |---:|---:|---:|---:|
 | 0 | Alice | 30 | Berlin |
 | 1 | Bob | 25 | Paris |
 | 2 | Charlie | 35 | London |

koperagen · 2026-04-02T11:08:49Z

I'm not so in favor of mandatory brackets :(

As for newlines in markdown, i didn't think about <br>, interesting it works! Tbh this all is confusing me. When i started i didn't know markdown is a superset of HTML. If this is the case, then why we even need this table renderer when we already have toStaticHtml? :)) But at the same time, this table format is not even "standard" markdown
Maybe it's worth to have it be plain ASCII for max compatibility and look again at toStaticHtml for advanced features? It's already more versatile

Jolanrensen · 2026-04-02T17:45:35Z

I'm not so in favor of mandatory brackets :(

It does provide a clearer picture, no? :) otherwise, we can always add a setting which turns it off. I liked them in the R table :)

As for Markdown... hmm, I think we could still offer it. It's like a hybrid between ascii and html, like, it's readable, but also renderable. I think there's some value in that. But then we should probably keep it as flat and simple as possible, because, as you say, for more advanced cases, we can just turn to HTML.
Maybe we could align it a bit with markdown output from interactive tables?

koperagen added 3 commits March 18, 2026 19:39

Add renderToString tests to safeguard refactoring

bb5636e

Extract data processing from renderToString

8df201b

Add renderToMarkdown

235a185

Fixes #525

koperagen requested a review from Jolanrensen March 18, 2026 18:13

koperagen self-assigned this Mar 18, 2026

koperagen added the enhancement New feature or request label Mar 18, 2026

Jolanrensen requested changes Mar 20, 2026

View reviewed changes

koperagen added 10 commits March 30, 2026 17:42

Fix DataRow.toString always using .6f precision formatting

4671a11

Apply "might be const" fix

1ea5517

Refactor literals to const variables

04a2e29

Render column types on a separate line to avoid clutter

00abb78

Switch columnTypes = true by default

113f260

Move markdown to markdown.kt + code cleanup

679ef39

Increase spacing between columns for better rendering of "heavy" tables

239b666

Allow null values to disable limits in renderToString/Markdown

852dedd

Always print total size of truncated table

d9e3b22

Add border style parameter to AnyFrame.renderToString

b4f9e42

Jolanrensen reviewed Mar 31, 2026

View reviewed changes

Conversation

koperagen commented Mar 18, 2026

Uh oh!

Jolanrensen commented Mar 20, 2026

Uh oh!

Uh oh!

Jolanrensen Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

Jolanrensen Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

Jolanrensen Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

koperagen Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Jolanrensen Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

koperagen commented Mar 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Jolanrensen commented Mar 31, 2026

Uh oh!

koperagen commented Mar 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Jolanrensen Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

Jolanrensen Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

Jolanrensen commented Mar 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Jolanrensen commented Mar 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

koperagen commented Apr 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Jolanrensen commented Apr 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

koperagen commented Mar 30, 2026 •

edited

Loading

koperagen commented Mar 31, 2026 •

edited

Loading

Jolanrensen commented Mar 31, 2026 •

edited

Loading

Jolanrensen commented Mar 31, 2026 •

edited

Loading

koperagen commented Apr 2, 2026 •

edited

Loading

Jolanrensen commented Apr 2, 2026 •

edited

Loading