MDX Editing Guide

MDX files combine regular text and Markdown formatting with React components and custom components to create a feature-rich, flexible, and easy-to-use content editing experience.

The content of the MDX Editing Guide that you are currently reading is rendered from an MDX file called mdx-editing-guide.mdx, which you can find in the /content folder of the CCV website codebase. It's extremely meta.

Every page on the CCV website is rendered from an mdx, markdown, or yaml file in the /content folder.

All available components are in the /components folder. To make them accessible in .mdx files, add them to /mdx-components.tsx. Import the component(s) at the top of the file and add it to the Global MDX Components section at the bottom. To request a new custom component, please add an issue to the CCV website github repository.

Best practices:

1. Keep it simple - Use the styled components provided and create an issue on github to request a custom component.

• ❌ Don't use HTML tags directly
• ❌ Don't add complex styling or classes

2. Test your changes - Run npm run dev to see your changes

This is an example of an MDX content file containing custom components and markdown formatting.

// example-content-file.mdx
<ContentSection title="Welcome to the Wonderful World of MDX">
The `<ContentSection>` component is used to create a header for the page and apply styling to that page's section. It is a custom component that is defined in `/components/SectionHeader.tsx` and imported in `/mdx-components.tsx`. Every section of your page should be wrapped in a `<ContentSection>` component.

Insert a button that links to a markdown cheat sheet and the `@next/mdx` documentation using the `<Button/>` component. It uses the same styling as the buttons that are used throughout this website. The `<ButtonGroup/>` component is used to group buttons together.

<ButtonGroup>
  <Button href="https://www.markdownguide.org/cheat-sheet/">
    Markdown Cheat Sheet
  </Button>
  <Button href="https://nextjs.org/docs/app/guides/mdx">
    Read Documentation
  </Button>
</ButtonGroup>

Here is a non-exhaustive list of markdown formatting options:

- Use dashes for bullet points
- Like this
- And this
- Make a ***bold and italic*** list item
- Make a ~~strikethrough~~ list item

1. Make a numbered list item
2. Like this
3. And this
</ContentSection>

This is how the above example renders:

The <ContentSection> component is used to create a header for the page and apply styling to that page's section. It is a custom component that is defined in /components/SectionHeader.tsx and imported in /mdx-components.tsx. Every section of your page should be wrapped in a <ContentSection> component.

Insert a button that links to a markdown cheat sheet and the @next/mdx documentation using the <Button/> component. It uses the same styling as the buttons that are used throughout this website. The <ButtonGroup/> component is used to group buttons together.

Here is a non-exhaustive list of markdown formatting options:

• Use dashes for bullet points
• Like this
• And this
• Make a bold and italic list item
• Make a strikethrough list item

1. Make a numbered list item
2. Like this
3. And this