Readme undersells difficulty of using with TypeScript

[lbv-stripe]

What happened?

The readme suggests that using with TypeScript is as simple as installing a few files and setting up a tsconfig.json file. But there are some pretty steep roadblocks later on. The particular one I've hit is that for the config object you pass to Markdoc.transform, the compiler expects a very complicated type — per source/types.ts, it's

 type ConfigType = Partial<{
  nodes: Partial<Record<NodeType, Schema>>;
  tags: Record<string, Schema>;
  variables: Record<string, any>;
  functions: Record<string, ConfigFunction>;
  partials: Record<string, any>;
  validation?: {
    validateFunctions?: boolean;
  };
}>;

which is not something I know how to construct. The example config object given in the docs,

const config = {
  tags: {
    callout
  }
};

fails to typecheck. The docs give no guidance, and as a result, I can't use any of Markdoc's interesting features. I'd appreciate either an example in the docs of a config object that will typecheck or (if all else fails) a heads-up in the readme that TS wizardry is required.

To reproduce

I encountered this following the instructions here: https://markdoc.dev/docs/tags

Version

0.1.13

Additional context

This may not count as a full-fledged bug, and probably merits the "docs" label. Sorry for the confusion, this was my only option. :)

[mskri]

I agree. It's been a trial and error at times to figure out how to type things so that TypeScript is happy.

[bwnelb]

I also found the type check errors from examples to be jarring and instead of learning a Markdoc concept I started learning some TS instead. Might be good to note the "strict": false, tsconfig.json option if anyone wants a quick way to move past a type definition issue while exploring a new tool.

[JPrisk]

when working with typescript adding the following to your config saves some guess work:

import Markdoc, { Config } from "@markdoc/markdoc";

const config: Config = {
    ...
}

i'm reluctant to add this in a PR for the docs because it written for js atm

[fieldju]

when working with typescript adding the following to your config saves some guess work:

import Markdoc, { Config } from "@markdoc/markdoc";

const config: Config = {
  ...
}

i'm reluctant to add this in a PR for the docs because its primarily written for js atm

FWIW for JS purists, you can add this annotation to get intellisense and IDE errors (vs transpilation errors)

/** @type {import('@markdoc/markdoc').Config} */

So, in this case it'd look something like

/** @type {import('@markdoc/markdoc').Config} */
const config = {
    ...
}

Which would give you give you IDE warning/errors and intellisense

You can cmd+click into it to see the types too

[JPrisk]

ah, thats a good suggestion @fieldju - have put up a PR for the team to consider