[exploration] define how to express in mdx

[FFawzy]

write a test case /sample in the docs-kit

• check if the mdx file and the way we wrote MDX inside our component is acceptable to our authors
• write test cases in the docs-kit to try out and demonstrate to the editors what can and cannot be done.
• can we write plain markdown? (if not, total blocker, it should work)
• can we still use custom component inside markdown?

[gabriele-ct]

Here are my findings.

Proposed structure

<MultiPathBlock title="some title here">
  <PathBlock language="javascript">
   Some **javascript** content:
</PathBlock>
  <PathBlock language="php">
     Some **php** content:
  </PathBlock>
</MultiPathBlock>

Allowed markdown All the standard md syntax is supported, I can't see any issue with md typically editors use. Headings are to be avoided since the side navigation is built upon them and it will look broken if we use them inside a path block

Custom components Again, most of the component seem to be working fine as you can see here I found that SideBySide component is not working, MultiCodeBlock should be avoided since it's creating confusion. Other than that I could not see any other blockers. I even tested some of the self learning conditional rendering components, and they work fine.

Could you @FFawzy @nkuehn @zbalek have a look and let me know if I missed something important. Thank you

[gabriele-ct]

sorry, I had posted incomplete url: https://docskit-ga-multiple-path-exploration.commercetools.vercel.app/docs-smoke-test/views/multi-path-block

[FFawzy]

Nice, Thanks a lot @gabriele-ct , I'd say this is already a great start. I'd say lets continue writing some more specs for the MultiPathBlock component.

I'd suggest the PathBlock props are not bound to a language, since there will be usecases where it is pure content (eg, Merchant Center, Frontend Studio), I would vote for keeping the props simple to label: string, key: string where the label can be used for the UI and the key used for state

wdyt?

[gabriele-ct]

Definitely, I had thought about it. My only concern is about the "synchronisation" beetween the MultiPathBlock and the MultiCodeBlock. Has this been descoped? If not we would sync them only if there's an exact match between the label in one case and the language?

[gabriele-ct]

Also, do we need a title prop? I guess it depends on the designs but I guess we don't really need it, at least if we want to mimic the app kit component.

What we could define is a defaultLabel in case we want to select a specific tab (that is not the first) if nothing is selected? WDYT? useful?

[nkuehn]

Thanks for the proposal! My thoughts:

• Find an idea below for a more explicit "syncWith" attribute for the langaage key.
• default is the left most (first in the list). That's a consistent UX that authors cannot be messing with
• What do we need a title for? I did not see a place in the UX / UI where it would be rendered.
• As for the actual MDX our experience is to keep them as concise as possible. e.g.
• Would it work without the indentation? That's something authors struggle with often.
• Visible title might be more verbose than the language tag we use to sync state. in the Code blocks we maintain a hardwired list of mapping language tag to the display language because standard markdown blocks have only the language tag - but it's actually unnecessary hardcoded maintenance work.
• I think in our current MDX v1 you need to put extra blank lines before and after the embedded markdown.

What do you think of this:

<Paths>
<Path label="JS SDK v1" syncWith="javascript">

Some **javascript** content:

</Path>
<Path label="PHP SDK v3" syncWith="php">

Some **php** content:

</Path>
</MultiPath>

[gabriele-ct]

Thank you @nkuehn for your contribution. I've added the syncWith prop and renamed language to label, also the title prop was un-necessary, so I removed it.

Regarding the MDX: it will work without indentation, the only syntax caveat I've found is that in order to add extra breaking lines the editors will need to use the <br /> tag. I think it's a limitation of having md within jsx tags. You can see some examples here

If we're happy with the current spec, I'd ask the content editors to review it

[FFawzy]

Thanks @gabriele-ct, looks good. please start the discussion with a tech writer and Luke. since he will use it a lot too.

[nkuehn]

Thanks @gabriele-ct - that example is quite intense, I'm curious to see what of it works as a UX and what not.