ascii-tables: turn tab separated text into a table you can paste anywhere

A page, a text box and a button

ascii-tables is described as a tool to quickly format tables in ASCII, good for code comments or GitHub Markdown. The README opens with a link to play with it at ozh.github.io/ascii-tables, and the workflow it describes is one text box, some input, and a button.

The repository layout explains why it works that way. At the root there are .gitignore, README.md, an assets/ directory and index.html. There is no package.json, no build configuration, no source directory and no test suite. The default branch is gh-pages, which is the branch GitHub Pages serves. So the tool is a static page, and the whole application is a single HTML file with its assets.

That is a deliberate and reasonable shape for this kind of tool. Formatting a table is a two-second job that people do dozens of times a week in chat windows, commit messages and issue trackers, and a page you can bookmark is faster than anything that needs installing. There is also nothing to keep in sync with a build, and nothing that can break when a dependency moves.

The consequence for a developer is that this is a tool you use, not a library you depend on. The README describes pressing a button, and the repository does not document a module, a function or a command line entry point. If your workflow needs the formatting to happen automatically as part of a script or a commit hook, this repository as it stands does not offer that.

The licence is listed as unknown, which is a real limitation for anything beyond personal use, and it is covered further below.

Tab or four spaces, and rows that are allowed to be short

The input format is deliberately forgiving in one way and strict in another.

You paste plain text where the columns are separated by a tab or by four spaces, and the first line is treated as the header. The input shown in the README has four columns named Col1, Col2, Col3 and Numeric Column, with rows of two, three and one cell respectively.

That last row is the interesting one. A row with only one cell does not break the tool, it simply leaves the remaining cells empty in the output. The generated table shows the first cell filled and the rest blank, which means the tool pads short rows to the width of the longest one rather than rejecting them.

For a human pasting a snippet of log output or a partial query result, that is the right behaviour. You do not have to reconstruct a rectangle before you can format it, and you can paste the output of a command that produced ragged rows. The cost is that a column can end up mostly empty without any warning that your input was inconsistent.

The four spaces option is a convenience for people who copy from an editor that has converted tabs, and the separator is detected rather than configured, so the same paste works in either case.

One thing the README does not describe is how the numeric formatting works. Looking at the output, the value 123 in the third column is left aligned while 10.0 and -2,027.1 in the fourth column are right aligned, and the header of the fourth column is right aligned too. That suggests the rule is per column, where a column whose values are all numeric is right aligned so the decimal points line up.

Ten output dialects, and picking the wrong one is easy

The bulk of the README is a catalogue of ten rendering styles, and the variety is the point of the tool. The same input can be produced as an ASCII table in mysql style, separated style, compact style, Github Markdown style, Reddit Markdown style, reStructuredText Grid style, reStructuredText Simple style, Jira style, rounded style, bubbles style and girder style.

Here is the MySQL style output for that input:

+----------------------------------+---------+------------------------+----------------+
|               Col1               |  Col2   |          Col3          | Numeric Column |
+----------------------------------+---------+------------------------+----------------+
| Value 1                          | Value 2 | 123                    |           10.0 |
| Separate                         | cols    | with a tab or 4 spaces |       -2,027.1 |
| This is a row with only one cell |         |                        |                |
+----------------------------------+---------+------------------------+----------------+

And here is the same data as a GitHub Markdown table, which is the one you would paste into a comment or a pull request:

|               Col1               |  Col2   |          Col3          | Numeric Column |
|----------------------------------|---------|------------------------|----------------|
| Value 1                          | Value 2 | 123                    |           10.0 |
| Separate                         | cols    | with a tab or 4 spaces |       -2,027.1 |
| This is a row with only one cell |         |                        |                |

The dialects differ in more than border characters. The separated style uses a heavy equals rule under the header and thin dashes between rows, the compact style drops the vertical bars entirely, the reStructuredText variants use equals signs and no leading pipe, the Jira style uses the doubled pipe convention, the rounded style uses dots and colons, and the bubbles style replaces the frame with o, 8 and parenthesis characters.

For a user, the choice is mostly about where the text is going, and the Reddit Markdown variant in particular has a leading space before each pipe, which is a small detail that matters if you are pasting into a comment thread. GitHub Markdown and reStructuredText are the two most likely to appear in a code review or a documentation file.

Numeric columns get their own alignment, and the header follows

The alignment behaviour is visible in every output block and is worth understanding before you paste anything into a document where the numbers matter.

Text columns are left aligned, and the header of a text column is centred. The Numeric Column is different: 10.0 and -2,027.1 are right aligned under a right aligned header, so the decimal points and the digit columns line up vertically.

The threshold is per column rather than per cell. The third column holds 123, which is a number, but the column also holds with a tab or 4 spaces, so the column is treated as text and 123 is left aligned with the rest. The fourth column holds only numbers, so the whole column is right aligned. A thousands separator in -2,027.1 does not stop it being recognised as numeric.

This is the behaviour you would expect from a tool whose main use is showing results, and it is the kind of detail that a quick manual table never gets right.

The one caveat is that the README does not state the rule, it only demonstrates it. Those outputs do not cover a column that mixes numbers and blanks, a column of numbers with different widths, a column where only some rows are numeric, or how negative signs and decimal separators in other locales are treated. If your data is irregular in that way, the sensible thing is to paste your real input and look at the result rather than to assume the behaviour generalises.

Where a formatter like this actually earns its place

The stated use cases in the project description are code comments and GitHub Markdown, and those cover most of the real value.

A code comment that contains a table is a common and slightly awkward thing. You cannot use Markdown in a comment, and a hand-aligned table drifts the moment a value changes length. Generating the table means the alignment is correct at the moment you paste it, and if the data changes you regenerate rather than fix.

Issue trackers are the second case. Jira style and GitHub Markdown style both exist precisely because the target system has its own table syntax, and a renderer that emits that syntax saves you from getting the pipes wrong. The Reddit style covers the third case, where a leading pipe is required or the table does not render.

The reStructuredText styles point at a fourth audience. Documentation written in reStructuredText, which is still the markup for a lot of Python documentation tooling, has its own grid and simple table forms, and a generated one is more readable than a hand-aligned one in a source file.

So the tool is a small piece of formatting hygiene, and its value compounds: the same source text can be rendered in whichever dialect the destination needs, which is exactly the repetition the ten styles are designed to remove.

A static page with no documented API and an unclear licence

Two facts about the repository deserve a blunt assessment.

The first is the absence of a programmatic interface. The top-level entries are .gitignore, README.md, assets/ and index.html, and the README describes a button, not a function. There is no package published for it, no command line tool and no documented JavaScript entry point. If you want the formatting to happen inside a script, a commit hook or a continuous integration job, you would have to reverse engineer the page or write your own, and neither is documented.

The second is the licence. The repository lists the licence as unknown, and the README does not carry a licence section. There is no LICENSE file in the listing. For a tool whose output you paste into your own work, that is less severe than it would be for a library, since the generated table text is yours. But if you want to redistribute the tool itself, host the page on an internal server, or fold its code into an internal tool, you have no stated permission to rely on.

Neither of these is a reason to avoid the tool for personal or team use. They are reasons to know what you are getting, and to check the licence yourself before you build anything on top of the page.

What the project offers is a well-scoped, dependency-free formatter with a broad set of output dialects, and a README that demonstrates every one of them with the same input. That is a good deal more documentation than most tools of this size provide.

Maintenance without a release history

The last push to the repository was on 2026-08-07, and the project has no GitHub releases.

For a static page, that is a mild version of the story that matters for libraries. There is no version to pin, so a bookmark to the live site will change under you, and if the behaviour shifts, there is no earlier version to fall back to. The practical mitigation is trivial: save the HTML and the assets locally, or copy the output you need at the time you need it.

The daily or periodic updating question does not apply here in the way it does for a catalogue of live data, because the input comes from you. The only moving parts are the browser, the page, and the style list, and the style list is what the README documents, so you can see exactly what you are getting before you click.

There is also a practical point about where the tool lives. Since the default branch is gh-pages and the project is a GitHub Pages site, the URL ozh.github.io/ascii-tables is the same artefact as the repository. That means the tool is available to anyone, which is the right default for something this small, and it also means the entire source of the application is a file you can read in a browser's view source if you want to know exactly what it does with the text you paste.

For a tool with no sensitive inputs, that is a good deal. For one where you would paste internal data, the same transparency is reassuring, but the licence question is still the thing to settle.

Editorial conclusion

ascii-tables suits anyone who keeps tabular data in a code comment, a ticket, a pull request description or a reStructuredText file and wants aligned output in the dialect of the target system. It does not suit a production pipeline, because there is no documented library or command line interface and the repository is a static page, and it does not suit a company that needs a clear licence position, since the repository records the licence as unknown. Check three things before you adopt it: that the style you need exists in the list of ten, since the Reddit and reStructuredText Simple variants are not interchangeable with the GitHub one, that your source data really is tab or four space separated, since the tool assumes rectangular rows and pads the short ones, and that the alignment of a numeric column matches what your reader expects. The last push to the repository was on 2026-08-07 and there are no GitHub releases.

Frequently asked questions

Official sources

1. Issues
2. ozh/ascii-tables on GitHub
3. Project website
4. README