Show HN: Excel-like table editing for Markdown | Hacker News Reader

Show HN: Excel-like table editing for Markdown

blog.documentnode.io

246 pointsjakew82 comments

Looks really slick. Thanks for the contribution!

I don't know if this is sacrilege or not here but I really like reStructuredText's list-table directive [1] for this kind of thing. It provides a text-friendly editable representation that renders to a nice table. There's a CSV-based table directive also (scroll up one in the link).

   .. list-table:: Frozen Delights!
      :widths: 15 10 30
      :header-rows: 1

      * - Treat
        - Quantity
        - Description
      * - Albatross
        - 2.99
        - On a stick!
      * - Crunchy Frog
        - 1.49
        - If we took the bones out, it wouldn't be
          crunchy, now would it?
      * - Gannet Ripple
        - 1.99
        - On a stick!

I like Markdown a lot for simple things like notes and readmes. When I write technical documentation and when I wrote my e-book, RST had the extended feature set I needed.

[1] https://docutils.sourceforge.io/docs/ref/rst/directives.html...

When it comes to 'text-friendly' I far prefer nicely formatted MMD tables...

  | Treat         | Quantity   | Description                                                     |
  | :------------ | :--------  | :-------------------------------------------------------------- |
  | Albatross     | 2.99       | On a stick!                                                     |
  | Crunchy Frog  | 1.49       | If we took the bones out, it wouldn't be crunchy, now would it? |
  | Gannet Ripple | 1.99       | On a stick!                                                     |
  [Frozen Delights!]

...despite the comparative hassle in editing them. It's just so much more readable at a glance later.

Although it looks nice, tables and Markdown are not a good fit. The syntax for tables in Markdown is broken by design!

AsciiDoc got it right: https://asciidoctor.org/docs/asciidoc-syntax-quick-reference... You can even have formatted source code in AsciiDoc table cells. Try this with Markdown ...

> The syntax for tables in Markdown is broken by design!

can you elaborate?

The syntax simulates the visual representation of tables, but that doesn't scale for larger tables with many columns and/or large columns with a lot of content. Another downside is that you can not use markup, like bullet lists or source code formatting, in table cells.

Markdown tables are overly simplistic.

That's because the point of markdown is to be an overly simplistic styling convention that reads just as cleanly in clear text (eg on the terminal) as it does in formatted renderers. Tables weren't even part of the original design of markdown. In fact there's a lot of stuff that Github and others have bolted onto markdown.

The real problem with markdown is that now it has now reached the kind of critical mass where people start using it everywhere and reaching for it even when it doesn't make sense simply because it's the first thing that pops into peoples head.

So, in my personal opinion, if you start needing the kind of design sugar as formatted cells then you really should be using any one of the plethora of other document formats out there because you're requirement no longer fits around the core principle of markdown. A great many of which can still be composed in a text editor and some of which are still relatively easy for a human to parse.

[edit]

Getting downvoted on this so I'll provide some citations:

> "[Markdown's] key design goal is readability – that the language be readable as-is, without looking like it has been marked up with tags or formatting instructions"

Source: https://en.wikipedia.org/wiki/Markdown#History (Wikipedia, Markdown history)

> "A Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions. While Markdown’s syntax has been influenced by several existing text-to-HTML filters — including Setext, atx, Textile, reStructuredText, Grutatext, and EtText — the single biggest source of inspiration for Markdown’s syntax is the format of plain text email."

Source: https://daringfireball.net/projects/markdown/syntax (John Gruber, one of the co-creators of markdown)

> Markup offers an alternative means to encode this signaling information by overloading certain graphic characters (see, e.g., [ISO646]) with additional meanings. Therefore, markup languages allow for annotating a document in a syntactically distinguishable way from the text, while keeping the annotations printable.

Source: https://tools.ietf.org/html/rfc7763 (original RFC)

I totally agree with you. Markdown is nice as a pretty simple documentation format. It is a good fit for something like a letter, a README or a short tutorial. I you go beyond this level, you are better off with something more powerful like AsciiDoc.

From that point of view, tables should have never been part of Markdown.

Nit: tables are part of github-flavored markdown, not John Gruber's original Markdown.PL, and there's also another table extension syntax for markdown. Apart from that, the point of markdown is that you can drop to plain inline HTML/markup or markup blocks when markdown short syntax is insufficient, such as for complex table layouts. Regular markdown syntax really is made for plain text editing. As such, it would probably make more sense that a visual editor, cool as it looks, targets robust markup serialization (HTML-in-markdown) rather than producing markup shortform syntax IMO (but then again, the plethora of markdown editors may prove me wrong on this one).

This.

It seems like the OP would be better served by CommonMark or any of the alternate implementations which are designed to be more feature complete to solve these kinds of formatting problems.

Regardless, if you want to go down the rat hole of exactly what is Markdown, the only "correct" answer is 'whatever Gruber's 'markdown.pl' does, warts and all'.

> Getting downvoted on this so I'll provide some citations

That's what usually happens here on HN when you say "this is wrong" to the crowd doing that wrong thing.

I really agree with you so not asking in a snarky way, but which other document formats do you have in mind? Something like HTML?

AsciiDoc, Rst, Org mode, Latex come to mind

But tables in LaTeX are not fun, too. Once upon time I was about to write a bunch of big and complex tables with LaTeX and needed to include "mini pages" in table cells to be able to render complex content. It was so awkward that I stopped using LaTeX.

I don't think you're getting downvoted due a lack of sources.

Markdown has clearly been extended beyond its original intention, so the criticism on its inadequacy for tables is justified in that it is the de facto standard across platforms and folks are struggling with it.

Whatever its original design goal was is sort of besides the point now. People dislike having to type complex tables manually and not using Markdown isn't a choice in a variety of situations. That frustration is justified.

I find complex tables frustrating to read and write in AsciiDoc. The markup can be written in a way that visually does not resemble the resulting table at all; newlines within cells (apparently) require actual newlines breaking “one row per line of markup” intuitive mapping; syntax errors or mismatched col/rowspans are difficult to spot; and so on.

    h|row 1 |foo .2+|bar |baz 5+|newline +
    inside cell |last cell
    h|another row |bar .2+||||
    ...

I actually prefer reStructuredText’s approach[0], which while being a hassle to edit, at least ensures table markup visually resembles the result.

Overall I feel like having to manually edit a complex table is often a sign of a flawed process somewhere, and should ideally be eliminated—author data in a structured way, and render it as a table automatically. (In the end it depends, of course.)

[0] https://docutils.sourceforge.io/docs/user/rst/quickref.html#...

ReStructuredText also has list tables. And CSV tables. https://sublime-and-sphinx-guide.readthedocs.io/en/latest/ta...

There is also a vim plug-in that do much of the same, even handling formulas (!):

https://github.com/dhruvasagar/vim-table-mode/blob/master/RE...

Personally I prefer to keep my markdowns simple, as it was explicitly designed to be a simple markup readable in raw form. Often the constraints of simplicity force me to think deeper about what I'm trying to explain so as to fit the format; limitations can be a strength.

Possibly relevant for those looking for easier ways to create Markdown tables: A few years ago, I wrote a spec for Markdown tables using a subset of YAML -- no GUI required for authoring.

Curious what HN thinks of it: https://github.com/IFTTT/tablerize

I like it! Reminds me a bit of comma separated trees:

https://observablehq.com/@mbostock/comma-separated-tree

I’ll be that one person:

org-mode already does tables with formulas and all[1], if you’re interested in text-based spreadsheets

[1]: https://orgmode.org/manual/Tables.html

Recent convert but org mode columnar sums still look a bit tricky.

M-x org-md-export-to-markdown is my friend!

Sums of a whole column in org mode tables is among the simples formulas you can write for tables. Just call the sum function (vsum?), enter the start cell and end cell, and where you want to put the result. That's it. Except that it is text only, I don't see what's more difficult, than entering a formula in a GUI spreadsheet app.

The examples on the web have weird markup

I should write some examples for tables and put them in a repo somewhere. You are right, sometimes the examples require a bit of trying and a lot of thinking, before one can apply them. That should not be. However, once you figure it out, it is amazing ;)

Please do!

I used org-mode tables to tabulate student grades for a course I was teaching last semester. Summing single columns was okay. But I needed to drop selected assignments (had a column with 1s and 0s). And then had to figure out the percentage marks each student had in the assignment component.

It was honestly a huge pain. I could have written the formulas for this in under 15 min on a regular spreadsheet software. With org-mode I spent hours trying to figure it out. In the end I had a hacky solution that I don't want to use again.

this

..one person?

I admire your optimism.

And markdown-mode provides similar easy table editing for Markdown. This is what I have been using primarily on Linux.

On the Mac I also use TableFlip [1], which provides an Excel-like interface for tables and works with any Markdown editor that automatically reloads a file on changes. It's a one-time purchase, no subscriptions.

[1] https://tableflipapp.com

That looks cool. But if you want to have only one application to do the job, there is another option.

Yes! Nicely integrates with almost everything through org-mode's babel [1] (those not familiar with Emacs, org-mode babel is like Jupyter notebook on steroids). If you find org-mode table column formulas complicated, you can use other languages instead. Here is example with R [2].

For me org-mode became interface to glue other tools and languages, plus I get documenting facility for free. Just like bash/shell for unix tools.

[1] https://orgmode.org/worg/org-contrib/babel/

[2] https://orgmode.org/worg/org-contrib/babel/intro.html#spread...

That got a good laugh out of me. Very org-mode-user of you to call Babel "Jupyter notebook on steroids". Anyone else would take one look and say "wtf are you talking about?"

Uhm, could you elaborate? Org mode/Babel supports many languages and is feature rich. Why would you say, the statement "Babel is Jupyter notebook on steroids" is laughable?

That probably just means he or she thinks Org Mode looks ugly. People are shallow and way too into looks. At least that's what I tell myself when I fail to get people interested in Org mode. :)

Honestly, I meant that lightly. My apologies. I found it humorous because it followed the (gui-version)^2 format of emacs-like tool endorsements.

If you want an actual reason, the two are not even close. Jupyter is a multi-langauge kernel _server_. Also most of its users are data scientists and the things they care about are pandasDfs, charts, tables which makes html rendering much more capable. You might say there are plugins and ways to do all the things I mentioned org mode/babel, but that misses the point. They're very different products.

One thing that's really nice is using org-mode tables in another mode. For example, I use it for LaTeX tables. I edit the table inline using org-mode then "compile" it into the LaTeX version before saving the document. It's really cool.

I enable orgtbl-mode automatically in markdown-mode for that reason. It's the table bit as a minor-mode that you can use in any major mode.

https://typora.io/ is also excellent for that

https://support.typora.io/Table-Editing/

Looks so nice. Too bad their Debian repo https://typora.io/linux/ has gone away. Are the sources published somewhere? Seems like Github only has the website and some themes.

Editor extensions go along the way instead propriatery BS for stuff that should be foss in 2020.

Example - with VSCode you have Markdown all in one [1]

Just do "Format Current Table" and thats it, see a picture [2]. Along with column editing and other advanced editor features there is simply no need for anything else, such as excel like GUI.

When I see "pricing" on markdown editor, I really get nausea

[1] https://marketplace.visualstudio.com/items?itemName=yzhang.m...

[2] https://github.com/yzhang-gh/vscode-markdown/raw/master/imag...

The Free in FOSS is not for free as in free beer [1]. If you get nausea at people wanting to be compensated for their work, you have a problem.

[1]: https://www.gnu.org/philosophy/floss-and-foss.en.html

Nah, I get nausea at people wanting to be compensated for reinventing the weel.

Have you figured out a way to print rendered Markdown from VSCode? Or even just print rendered version to PDF?

The lack of this feature makes Markdown in VSCode a no-go for me.

Yeah.

All in one markdown has PDF export. I use it all the time.

I built a little tool a while ago that converts CSV/TSV to Markdown. I use it mostly o convert MySQL EXPLAIN's to Markdown for pull requests.

https://donatstudios.com/CsvToMarkdownTable

Latex failed for me in table generation. It is great to write without concerns about formatting, but it is really hard to create a table in Latex. Hope Markdown solves this problem, but it isn't easy to solve the usability issues.

Writing raw latex sort of sucks for more than tables. You need a specialized editor/plugin for your favorite editor. I like LyX a lot!

I have recently bought an app for macOS that helped me handling tables in markdown: https://tableflipapp.com/

It does one thing and it does it well.

Needing tools to edit markdown seems to defeat the point, doesn't it?

Very nice! It would be really cool if you can do some simple math too, like =sum(...), and have it update the markdown for you. I like it!

You mean, like in org mode tables?

I've seen reference to org mode quite a few times now. I will have to check it out.

It's a massive, huge, enormous thing.

It will seem daunting at first. Especially if you have to learn Emacs as you go.

https://orgmode.org/worg/org-tutorials/org4beginners.html

That tutorial seems pretty good, it starts from the absolute beginning.

@fortylove That's a really good idea. I'm going to add simple math in the table editor.

I wrote this filter for Pandoc once that allowed you to execute Python from within cells and replace the cell content with the results. It also used row names as variable names.

Sadly, I can't find the markdown file that actually uses it and I also can't remember how it worked.

But the point is: you can do it (badly, but working) in ~100 of Python code as a plugin for Pandoc.

Oh, this is interesting! I created a webpack loader for markdown files because I use tables to store config and test data (https://www.npmjs.com/package/mdconf-loader) -- formatting in vscode already helps, but this will take it to another level.

After simply opening a md file, I found that Document Node corrupted it (linebreaks disappeared and content replaced with garbage characters).

Fortunately, the file was in a git repo, so I was able to revert and no harm done, but that does not exactly inspire confidence...

Thanks for letting us know about the issue. Was your document in a different encoding rather than UTF-8? We will find it out and fix it shortly.

Document in question is https://github.com/useful-bytes/netsleuth/blob/v1.0.9/README...

It's UTF-8 with unix line endings.

See also https://stevecat.net/table-magic/ for quickly editing and translating tables between CSV/TSV/HTML/Markdown/SQL.

This is good but it'd be even better inline, the same way Bear both displays markdown and shows the markers, you could imagine that the "Excell" UI could be embedded inside the plain text editor.

That's a very interesting idea. Something worth having a research. I've taken notes for it. Thanks.

I'd adopt this immediately if it could integrate with editors like vscode

While we wait for somebody else to implement this, here is a first step: Install the `prettier` extension and turn on autoformat for markdown.

It makes entering tables much easier and the tables more readable.

My table needs are rather simple but I use: http://www.tablesgenerator.com/markdown_tables

Hmmm, it's at this point I really want to improve the docutils/sphinx table handling...

Hope the markdown table can support some high-level options like function, I'll love it。

I will add simple functions in the next version. Specifically in two or three weeks. I promise.

Your demo doesn't show any cell padding. Is this the case for the final product? If so, is that something you're working on?

I'm not a huge fan of tables in markdown but if they're necessary then it should at least be readable in clear text and without padding it's not.

eg with padding:

    | which | column | is  | the | value | foo | in | ? |
    |-------|--------|-----|-----|-------|-----|----|---|
    |       |        | foo |     |       |     |    |   |

vs without padding

    | which | column | is | the | value | foo | in | ? |
    |-------|--------|-----|-----|-------|-----|----|---|
    |  |  | foo |  |  |  |  |  |

I have thought about this. Padding works when the text in a cell is not too long. When cell texts are arbitrary long, "padding" doesn't make sense any more.

Document Node is not just a pure Markdown editor, it has a beautiful HTML5 preview area, where you can see your tables in a perfect format. You can define your own styles using CSS, although we have 11 preview styles built-in.

Having said that, I think it's a good idea to give the users the option to enable padding. I will add that option in a later version.

There never be a final product for us and stop there, we will keep improving it and roll new versions frequently.

> I have thought about this. Padding works when the text in a cell is not too long. When cell texts are arbitrary long, "padding" doesn't make sense any more.

I do understand your point but you could also argue that's when you need padding the most because it becomes infinitely harder to visually parse the raw text.

I like your idea for giving people the option though.

> Document Node is not just a pure Markdown editor, it has a beautiful HTML5 preview area, where you can see your tables in a perfect format.

Document Node is a nicely polished product but it's worth remembering that the point of markdown is that it's still readable without needing a viewer that supports rich formatting. For example it should be just as readable in the terminal as it is in a HTML5 container (this is one of the reasons I don't really like tables in markdown but that ship has already sailed). Unfortunately not everyone will be using Document Node to view their markdown.

Thanks for your comment. It totally makes sense.

Sometimes, it is the art of balance. As a product, the goal is to save users time as much as possible. Eventually, the users have to decide whether it's appropriate to put a super complex table in Markdown, although it will be fine for tables with short rows.

While I'm writing this reply, I thought of how to improve this in Document Node. It can automatically check and add padding depending on whether any Markdown rows exceed 80 characters (or similar). One less thing to worry about.

OT - has anyone ever managed to make a decent text-based spreadsheet file format?

@jakew can your product work as front-end for Joplin?

Not sure about the notes format of Joplin. If it's Markdown files, then yes, you can open any Markdown folders in Document Node.

However, many users are using Document Node for notes taking, as it provides the most flexible way to arrange your content simply in folders.

What do you think of Markdown forms ?

I haven't evaluated how important is that for daily uses. :) I saw there was a discussion in CommonMark's forum.

what gui library does this app use？It seems cool.

Thanks for letting us know you think it's cool. :)

The GUI library is QT. But not ordinary Qt, we did lots of customization. A large amount of time invested in polishing it.

Thanks for clarify. The tiny version of Qt you polished is the key weapon behind the product.

I always pay attention to GUI/render related projects.

I don't need a software that require me to sign in before use.

Reply on news.ycombinator.com