"Rich" value formatting nasty with simple text

Developers Central
1

I want to use Coda as a headless CMS. For that reason I need to get formatted data out of the fields present in a Coda document. For this, the “rich” formatting option for “valueFormat” in the API is just splendid - I get Markdown, which is exactly what I want.

However, the documentation states:

  • For text values, returns data in Markdown syntax. If the text field is simple text (e.g. has no formatting), the field will be fully escaped with triple-ticks. E.g ```This is plain text```

The simple text part of this is really not really nice. Fully escaping the text with triple-backtics is not an escape in Markdown, it’s formatting! Triple backticks mean the same thing as a <pre> block in HTML. So every simple text field will be shown with a fixed with font. This is not something that is useful.

I believe the reason you do this is that you have special datatypes for “simple” fields and fields with formatting. For the simple fields you can’t simply return the contents as is, because otherwise they would be interpreted as Markdown by the recipient - so you need to escape the contents.

However, this means of escaping changes the meaning, and is not really transparent for consumers. Instead, I would suggest you use something like markdown-escape - npm (in your programming language of choice) to actually escape all the input in a way which does not change the meaning.

2

Thanks for this suggestion! That makes a lot of sense, we’ll look into this when we do some cleanup on our API output for text cells.

The triple-backtick “escaping” for valueFormat=rich was a half-measure that is largely a workaround for some nuanced internal use cases. The intention is that if you see a value that is completely surrounded in triple-backticks, treat it as a plain text and don’t feed it through a Markdown processor at all (fully recognizing that you can’t disambiguate this case from a rich value whose entire contents are <pre> formatted).

Robustly escaping Markdown control characters is indeed the better solution and we’ll look into finally cleaning that up.

1 Like
3

Indeed:

const escape = require('markdown-escape');

  if (md.startsWith('```') && md.endsWith('```')) {
    md = escape(md.substring(3, md.length - 3));
  }

And since it isn’t possible to switch valueFormat=rich on for a single column, all the “non rich text” fields also come as markdown formatted, and might have fun characters if there’s a bold or something accidentally in the field. So for those cases, I do:

const remark = require('remark');
const strip = require('strip-markdown');

function mdToPlain(md) {
  if (md.startsWith('```') && md.endsWith('```')) {
    md = escape(md.substring(3, md.length - 3));
  }
  ret = remark().use(strip).processSync(md, { commonMark: true }).toString();
  return ret;
}

Not the most convenient, or performant, but gets the job done.