adobe / adobe/aio-theme

Adopt MDX v2 for interleaving markdown and JSX

Open
#1,389 2 comments 0 reactions 1 assignee Claimed by @timkim View on GitHub
Dominant language
JavaScript
Stars
77
Forks
47
PR merge metrics
No merged PRs in 30d

Description

# 🙋 Feature Request

Hi Adobe I/O team, I wanted to request adoption of MDX v2 in order to enable [interleaving of JSX and markdown](https://github.com/mdx-js/mdx/issues/628), as solved in https://github.com/mdx-js/mdx/pull/1039.

## 🤔 Expected Behavior

My understanding (and please let me know if I'm mistaken!) was that the `` tag needs to use the `repeat=x` system because in MDX v1 it's not possible to have constructs like this:

```

#### Java

**Syntax**

\```java
public static String extensionVersion();
\```

```

## 😯 Current Behavior

And instead currently require this:
```

#### Java

**Syntax**

\```java
public static String extensionVersion();
\```
```
Which can be quite cumbersome to keep track of and update, especially when making a lot of structural/content changes across a documentation repo.

Potentially related, I found this known limitation of MDX v1: https://github.com/adobe/aio-theme/blob/a2bdb5257889138379b95b380353e8aad1e0d098/packages/gatsby-theme-aio/src/components/MDXFilter/index.js#L69

## 💁 Possible Solution

Adopting changes from https://github.com/adobe/aio-theme/pull/1383 (not sure what other changes/testing would be required).

## 🔦 Context

In the Adobe Experience Platform Mobile SDK docs using Adobe I/O, we use a lot of code tabs to show snippets and examples, and each of those tabs use `` blocks to show the tab content: https://developer.adobe.com/client-sdks/documentation/consent-for-edge-network/api-reference/#registerextension

Making sweeping changes to the structure or content of these blocks can be hard because you have to keep track of and update all the repeat counts. Being able to mark the start and end of ` ... ` blocks using interleaved JSX would make it a lot easier to maintain the docs.

## 💻 Examples

https://github.com/AdobeDocs/aep-mobile-sdkdocs

## 🧢 Your Company/Team

Adobe/Experience Platform Mobile SDK

## 🎁 Tracking Ticket (optional)

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.