[WEB-3888] Introduce support for MDX templating #2527
Conversation
|
Important Review skippedAuto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the You can disable this status message by setting the 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
jamiehenson
force-pushed
the
web-3888-mdx
branch
from
51562a4 to
26135c8
Compare
jamiehenson
force-pushed
the
web-3888-mdx
branch
from
26135c8 to
045ef0a
Compare
jamiehenson
force-pushed
the
web-3888-mdx
branch
from
0cd6592 to
2140107
Compare
jamiehenson
force-pushed
the
web-3888-mdx
branch
from
2140107 to
8c9835c
Compare
| @@ -0,0 +1,68 @@ | |||
| import { useEffect } from 'react'; | |||
There was a problem hiding this comment.
Basically, the whole reason for this is because we can't set customIds via gatsby-remark-autolink-headers. The plugin offers that functionality, but we're held back by the requirement that this Gatsby project adhere to ES Modules - which is a bit of tech debt @m-hulbert and I have discussed. It holds us back from a number of other remark plugins as well.
Small t-shirt, but still a blocker.
To get around this, we bodge in custom link tags and travel the DOM for them.
| }; | ||
|
|
||
| // Table components with responsive styling | ||
| const Table = (props: React.HTMLAttributes<HTMLTableElement>) => ( |
There was a problem hiding this comment.
Very minimal table styling. This is basically here to expose an entry point for better styling later.
There was a problem hiding this comment.
Better styling is still on the table 🥁 (I'll see myself out now)
|
|
||
| const WrappedAside = (props: PropsWithChildren<{ 'data-type': string }>) => { | ||
| return ( | ||
| <Aside |
There was a problem hiding this comment.
These are also temporary. Converting to ES Modules will allow us to use Github-inspired "admonitions" plugins which would give us those "note" blockquotes and stuff out of the box and put this old component to rest.
| export const onCreatePage: GatsbyNode['onCreatePage'] = ({ page, actions }) => { | ||
| const { createPage } = actions; | ||
| // Function to extract code element classes from an MDX file | ||
| const extractCodeLanguages = async (filePath: string): Promise<Set<string>> => { |
There was a problem hiding this comment.
A first go at something a little less "runtime". Since the syntax for defining codeblocks is set by Markdown which is quite rigid itself - we can dig through MDX files for present languages and build a representative superset that way. Textile files are still determined at runtime as they are still tied into the half-Textile-half-React world.
There was a problem hiding this comment.
This is nice! It would have been super convenient if the raw content of the file was available in onCreatePage, then you could forego all the duplicate IO (just a wishlist item)
jamiehenson
force-pushed
the
web-3888-mdx
branch
from
8c9835c to
a73f316
Compare
jamiehenson
changed the title
jamiehenson
force-pushed
the
web-3888-mdx
branch
from
a73f316 to
e500240
Compare
| [HtmlDataTypes.article]: Article, | ||
| [HtmlDataTypes.section]: Section, | ||
| [HtmlDataTypes.aside]: Aside, | ||
| [HtmlDataTypes.aside]: (props) => { |
There was a problem hiding this comment.
This is a bit wonky, but a circular dependency arises when using Aside outside of this context - like we do in MDXWrapper as a temporary means before we can use cleaner, Markdown-derived aside components. The bandage here is to load this on demand instead of webpack's normal module loading.
Alternatively, if the dust settles and GFM asides are still a no go, we can consider React-oriented admonitions like this: https://github.com/nebrelbug/react-admonitions
There was a problem hiding this comment.
This is really great @jamiehenson I think the code for extracting code from MDX file and formatting is really clever. I wait for @kennethkalmer to have final review for this as the expert. but I only have feedback if it possible
There was a problem hiding this comment.
That is slick (and sick) @jamiehenson. One of those things where the diff betrays how much work went into it.
Just remember @m-hulbert's ask to revert the actual content changes before merging!
| export const onCreatePage: GatsbyNode['onCreatePage'] = ({ page, actions }) => { | ||
| const { createPage } = actions; | ||
| // Function to extract code element classes from an MDX file | ||
| const extractCodeLanguages = async (filePath: string): Promise<Set<string>> => { |
There was a problem hiding this comment.
This is nice! It would have been super convenient if the raw content of the file was available in onCreatePage, then you could forego all the duplicate IO (just a wishlist item)
| }; | ||
|
|
||
| // Table components with responsive styling | ||
| const Table = (props: React.HTMLAttributes<HTMLTableElement>) => ( |
There was a problem hiding this comment.
Better styling is still on the table 🥁 (I'll see myself out now)
|
The CodeSnippet component was most of the diff for this tbh 😄 |
This PR introduces a successive approach to using the Textile templating language - the long-awaited MDX. As a result of this PR, two templates are converted which correspond to the following pages (situated on the review env for ease):
/chat: https://ably-docs-web-3888-mdx-xsqhpiy.herokuapp.com/docs/chat/chat/rooms/messages: https://ably-docs-web-3888-mdx-xsqhpiy.herokuapp.com/docs/chat/rooms/messagesMDX pages are placed in
src/pagesto utilise Gatsby's standard routing. Within these templates, normal Markdown syntax is supported as expected, but this PR also introduces the means to do certain other things that bridge the gap to functionality with the older Textile templates:Ifcomponent is a basic conditional block. It takes alangprop in the form of a string consisting of accepted languages joined by commas (i.e."javascript,swift,ruby). If the active page language (determined by the overall page context) matches one of these languages, then the child content is rendered, and vice versa.Example:
Codecomponent (an alias forCodeSnippet, for ease) is a rich code snippet that's best demonstrated in Storybook - it has a run down of various props and modifications. Its child elements are Markdown code snippets (denoted by three backticks either side) - whatever the language qualifier is for each snippet determines how it's represented as a tab in theCodeSnippet.Example (spaces added to backticks to allow rendering in this description):
I'll add some testing before merge, but I want to get the ball rolling on reviews first and get onto any queries or questions.
Word of bot
This pull request introduces multiple changes focused on improving MDX file handling, adding support for GitHub Flavored Markdown (GFM), and enhancing the layout and functionality of the documentation platform. Key updates include the introduction of an
MDXWrappercomponent, improved handling of code snippets and headers, and updates to dependencies and configurations.Enhancements to MDX Handling:
MDXWrappercomponent to provide a structured layout for MDX files, including support for custom components likeCodeSnippet, responsive tables, andAsideblocks. This component integrates with the layout context to manage active languages and page-specific features. (src/components/Layout/MDXWrapper.tsx, [1] [2] [3] [4]Ifcomponent to conditionally render content in MDX files based on the active language. (src/components/Layout/mdx/If.tsx, src/components/Layout/mdx/If.tsxR1-R20)Improved Markdown and Header Features:
gatsby-remark-autolink-headersplugin to add clickable and copyable headers in Markdown files, including a utility hook (useCopyableHeaders) for setting header links dynamically. (gatsby-config.ts, [1] [2]MarkdownProviderto allow overriding default components and added support for GitHub Flavored Markdown (GFM) via theremark-gfmplugin. (src/components/Markdown/MarkdownProvider.tsx, [1] [2] [3]Updates to Layout Context:
LayoutContextto include page-specific context, such as available languages and frontmatter data, enabling better integration with MDX files. (src/contexts/layout-context.tsx, [1] [2] [3]Dependency and Configuration Updates:
package.jsonto includeremark-gfm,gatsby-remark-autolink-headers, and other related packages, and upgraded existing packages likegatsby-plugin-mdx. (package.json, [1] [2] [3].prettierignoreto exclude MDX files insrc/pagesfor better inline rendering. (.prettierignore, .prettierignoreR1-R3)Removal of Deprecated Content:
content/chat/index.textilefile, which contained outdated documentation for the Ably Chat product.These changes collectively enhance the platform's ability to handle MDX files, improve the user experience with Markdown content, and streamline the integration of language-specific features.