Building your own blog article site and rendering Markdown content with Next.JS isn't difficult - there are a lot of different ways to get the job done.  For Serverless DNA we opted to use the **react-markdown** package which utilises a combination of **remark** and **rehype** to process and render the Markdown content into HTML.  This provides a good outcome and also provides some control over how particular aspects of Markdown can be rendered.  In our builder journey, we found the documentation and examples of customisation for react-markdown to be a little "Hacky".

One of the customisations we made is in the rendering of **code** blocks, we wanted to add in the **Prism SyntaxHighligher** which provides themed rendering of code blocks.  Integrating the Prism SyntaxHighlighter component is described in the main github page of the npm package, [here](https://github.com/remarkjs/react-markdown#use-custom-components-syntax-highlight).  As you can see from the in-line sample the customisation for rendering Markdown is handled in the **components** attribute, which works when applying a single customisation, but when one or more customisations are needed or planned, the code becomes un-maintainable very quickly. 

```js
import React from 'react'
import ReactDom from 'react-dom'
import ReactMarkdown from 'react-markdown'
import {Prism as SyntaxHighlighter} from 'react-syntax-highlighter'
import {dark} from 'react-syntax-highlighter/dist/esm/styles/prism'

// Did you know you can use tildes instead of backticks for code in markdown? ✨
const markdown = `Here is some JavaScript code:

~~~js
console.log('It works!')
~~~
`

ReactDom.render(
  <ReactMarkdown
    children={markdown}
    components={{
      code({node, inline, className, children, ...props}) {
        const match = /language-(\w+)/.exec(className || '')
        return !inline && match ? (
          <SyntaxHighlighter
            children={String(children).replace(/\n$/, '')}
            style={dark}
            language={match[1]}
            PreTag="div"
            {...props}
          />
        ) : (
          <code className={className} {...props}>
            {children}
          </code>
        )
      }
    }}
  />,
  document.body
)
```

The example is also Javascript and not Typescript so we also had to figure out the Typing of our custom components for them to be effective, this was not a simple as we first thought (being new to Typescript is more than likely why this was hard).  

We decided to create our own custom Markdown wrapper component so we could customise markdown rendering and not have to expose that to the main blog pages housing our content.  Our custom markdown component is shown below.  As you can see the outcome of applying customisations is identical to the react-markdown example, except we are not in-lining our code.  Instead we have imported our own rendering functions which enable customisation of Markdown rendering.  We have applied custom rendering to **code**, **a**, **img** and **blockquote**.  Image and Links we decided to customise so we could render them using the Next.JS components instead of the existing vanilla HTML tags and blockquote we wanted to provide our own look and feel.  For the remainder fo this article we will focus on the **CodeHighlight** component and how we integrated it.

```ts
import ReactMarkdown from 'react-markdown';
import { ReactMarkdownOptions } from 'react-markdown/lib/react-markdown';
import remarkGfm from 'remark-gfm';
import CodeHighlight from './markdown/codeHighlight';
import Link from './markdown/link';
import Image from './markdown/image';
import Quote from './markdown/quote';

export default function Markdown({ children, className, linkTarget }: ReactMarkdownOptions) {
    return (
            <ReactMarkdown 
                className={className}
                linkTarget={linkTarget}
                components={{
                        code: CodeHighlight,
                        a: Link,
                        img: Image,
                        blockquote: Quote,
                }}
                remarkPlugins={
                    [
                        remarkGfm,
                    ]
                }
            >
                { children }
            </ReactMarkdown>
    );
}
```

## Rendering Code with Syntax Highlighting

Customising redering of the **code** markdown block you must provide an function implementation to be called by the Markdown component.  In this case you can create a function containing the in-line code and needed to hunt down the Type declaration for the function type.  To be able to access the properties for the code block we needed to hunt down the **CodeProps** that are passed to the rendering function, being new to Typescript this took a little trial and error and detective work.  We needed to make sure we found the types passed into the render function and not the return type of the function.  To find the actual Property type we needed to explore up the type tree using VS Code through clicking on types and exploring up the hierarchy.  We started with Our markdown component whiuch took us to the component return type:

```js
export type SpecialComponents = {
  code: CodeComponent | ReactMarkdownNames
  ...
}
```

From here you can explore to **CodeComponent**

```js
export type CodeComponent = ComponentType<CodeProps>
```

and finally we get to **CodeProps** - this is the one you need!

```js 
export type CodeProps = ComponentPropsWithoutRef<'code'> &
  ReactMarkdownProps & {
    inline?: boolean
}
```

With this type we are now able to create the rendering function to provide a clean rendering function that also satisfies the strict es-lint rules setup by the default Next.JS project.  To keep things clean create a **markdown** sub-folder in your **components** folder and place all custom markdown render functions in this folder.  In this way we end up with a clean set of files that are easy to find.  Each cusomt function is in it's own file and we can import and use these render customisations quickly and easily.

This is how we managed to provide a clean framework to customise rendering of Markdown for Serverless DNA, we hope you find it useful in your Markdown rendering journey.  In the following sections is the code for each of our Markdown customisations which you may find useful in your Next.JS project.

### CodeHighlight Render Function

```js
import { CodeProps } from 'react-markdown/lib/ast-to-react';
import {Prism as SyntaxHighlighter} from 'react-syntax-highlighter'
import {dracula as codeStyle} from 'react-syntax-highlighter/dist/cjs/styles/prism'

export default function CodeHighlight({node, inline, className, children, ...props}: CodeProps) {
    const match = /language-(\w+)/.exec(className || '')
    let widget;
    const classes = `${className} `
    if(!inline && match) {
        widget = (
            <SyntaxHighlighter
                style={codeStyle}
                language={match[1]}
                className={classes}
                PreTag="div"
                {...props}
             >
                {String(children).replace(/\n$/, '')}
            </SyntaxHighlighter>
        );
    } else {
        widget = (
            <code className={classes} {...props}>
                {children}
            </code>
        );
    }
    return widget;
}
```

### Image Render function

```js
import NextImage from 'next/image';
import React from 'react';

type IImageProps = React.DetailedHTMLProps<React.ImgHTMLAttributes<HTMLImageElement>, HTMLImageElement>;

export default function Link({src,className, alt, children}: IImageProps) {
    className = `${className} img-fluid`
    return (
        <>
            <NextImage 
                src={src || ''}
                className={className}
                width={800}
                height={500}
                alt={alt || 'un-named blog article Image'}
                
            >

            </NextImage>
        </>
    )
}
```

### Link Render function

```js
import NextLink from 'next/link';
import { ReactNode } from 'react';
import React from 'react';
import { ComponentPropsWithoutRef } from 'react-markdown/lib/ast-to-react';

type ILinkProps = React.DetailedHTMLProps<React.AnchorHTMLAttributes<HTMLAnchorElement>, HTMLAnchorElement>;

export default function Link({href,className, children}: ILinkProps) {
    return (
        <NextLink
            href={href||''}
            className={className}
            target="_blank"
        >
            {children}
        </NextLink>
    )
}
```


### Quote Render function

```js
import React from 'react';

type IQuoteProps = React.DetailedHTMLProps<React.BlockquoteHTMLAttributes<HTMLQuoteElement>, HTMLQuoteElement>;

export default function Quote({className, children}: IQuoteProps) {
    className = `${className||''} p-4 mx-auto  shadow rounded-4 w-75 text-center align-middle bg-light`
    return (
        <>
            <div className="my-4">
                <div 
                    className={className}
                >
                    <blockquote className='blockquote'>
                        <em>
                            {children}
                        </em>
                    </blockquote>
                </div>
            </div>
        </>
    )
}
```

Customising Markdown Rendering

Using Next.JS and react-markdown to render the static site content for Serverless DNA works great, except where code blocks are concerned using **```**.  During development and testing, we found that code blocks rendered fine, until we started testing on smaller screens and mobile.  On Serverless DNA pages we use **bootstrap 5** for CSS and styling and to center code blocks a combination of **flexbox** and **center** styles is quite common.  

Code blocks are rendered inside a <pre> tag when long lines of code extend beyond the screen width, causing the tag width to be sized so that the code pushes beyond the screen edge.  With the large code block expanding this way the parent flexbox container is also re-sized - but not just around the code container but across the entire blog content, which makes the entire blog page render weirdly, see the screen-shot below.

![badly rendered web page](/strands/serverless-dna-evolution/responsive-md-codeblocks/bad-render.png)


There is a definitive CSS answer for why this occurs and it is discussed in more detail in [this article](https://weblog.west-wind.com/posts/2016/feb/15/flexbox-containers-pre-tags-and-managing-overflow).  The fix for Serverless DNA was to not use Flexbox for centering blog content and switched to using Bootstrap's grid system via the **row** class.  Doing this removed the problem for our blog article pages altogether, hopefully, this article will help someone trying to work out why their Next.JS code blocks break the rendering of the rest of their markdown content.



Responsive Markdown Code Blocks

Follow the evolution of Serverless DNA.  We will write about Site specific articles here covering learnings and challenges.

Customising Markdown Rendering

Responsive Markdown Code Blocks

About Serverless DNA

Fundamentals