Docz: Does Docz support syntax highlighting outside of Playground?

Created on 11 Sep 2018 · 8Comments · Source: doczjs/docz

Question

Does Docz support syntax highlighting outside of the Playground component?

Description

In addition to adding React component documentation, I am using Docz to document an entire system, at least half of which has nothing to do with React. Therefore, I need the ability to add "other" code snippets with the appropriate syntax highlighting.

For example, this does not seem to work:

Inside my file.mdx:
screen shot 2018-09-10 at 6 56 11 pm

It produces the following in thedocz-theme-default theme:

screen shot 2018-09-10 at 6 53 01 pm

The syntax highlighting for SCSS is not working. Syntax highlighting outside of the Playground, in general, does not work well, even for Javascript snippets.

Am I doing something wrong? Does Docz support this? Or maybe this is an MDX problem?

If this does not work, how can I help?

Source

meebix

Most helpful comment

@pedronauck - I think we should reopen this. The above gets rid of the "Codemirror not defined" error, but the hightlight does not work. Let me explain what I tested.

From the Codemirror docs, it appears that hightlighting for scss or less comes directly from the CSS mode in the form of mime types, which are text/x-scss and text/x-less. Therefore, you do not need to import another package. Importing the CSS mode is good enough.

You would think you could also pass mode: 'scss' but for some reason you cannot. The highlighting does not work.

screen shot 2018-09-12 at 2 50 45 pm

It does work if you pass mode: 'text/x-scss'.

screen shot 2018-09-12 at 2 52 52 pm

Weird, right?

Since you already import the CSS package here: https://github.com/pedronauck/docz/blob/master/packages/docz-theme-default/src/components/ui/Editor/index.tsx#L21

I propose that to at least support scss and less in addition to css, we make an immediate change like this:

const getLanguage = (children: any) => {
  const defaultLanguage = 'jsx'
  if (typeof children === 'string') return defaultLanguage
  const language = get(children, 'props.props.className') || defaultLanguage
  const result = language.replace('language-', '')
  if (result === 'js' || result === 'javascript') return 'jsx'
  if (result === 'scss') return 'text/x-scss'
  if (result === 'less') return 'text/x-less'
  return result
}

Link to code

Down the road, more changes will be necessary to allow syntax highlighting for other languages such as "Ruby" for instance.

It does not seem that adding a package like https://cdnjs.cloudflare.com/ajax/libs/codemirror/5.40.0/mode/ruby/ruby.min.js will be good enough to support different syntax highlighting for different languages.

What do you think?

meebix on 12 Sep 2018

👍6

All 8 comments

By default and because some performance issues, we're just importing some syntax highlighting with for Codemirror, but you can import by yourself just by adding some scripts on <body> using htmlContext on your doczrc.js, like that:

// doczrc.js
export default {
  htmlContext: {
    body: {
      scripts: [{
        src: 'https://cdnjs.cloudflare.com/ajax/libs/codemirror/5.40.0/mode/sass/sass.min.js'
      }]
    }
  }
}

pedronauck on 11 Sep 2018

👎1

@pedronauck - This does not work as is. It throws an error in the browser console "Codemirror is not defined".

I don't think getting additional syntax highlighting is this simple. I will investigate.

meebix on 12 Sep 2018

Try with this:

export default {
  htmlContext: {
    body: {
      scripts: [{
        src: 'https://cdnjs.cloudflare.com/ajax/libs/codemirror/5.40.0/codemirror.min.js'
      },{
        src: 'https://cdnjs.cloudflare.com/ajax/libs/codemirror/5.40.0/mode/sass/sass.min.js'
      }]
    }
  }
}

pedronauck on 12 Sep 2018

@pedronauck - I think we should reopen this. The above gets rid of the "Codemirror not defined" error, but the hightlight does not work. Let me explain what I tested.

You would think you could also pass mode: 'scss' but for some reason you cannot. The highlighting does not work.

screen shot 2018-09-12 at 2 50 45 pm

It does work if you pass mode: 'text/x-scss'.

screen shot 2018-09-12 at 2 52 52 pm

Weird, right?

Since you already import the CSS package here: https://github.com/pedronauck/docz/blob/master/packages/docz-theme-default/src/components/ui/Editor/index.tsx#L21

I propose that to at least support scss and less in addition to css, we make an immediate change like this:

const getLanguage = (children: any) => {
  const defaultLanguage = 'jsx'
  if (typeof children === 'string') return defaultLanguage
  const language = get(children, 'props.props.className') || defaultLanguage
  const result = language.replace('language-', '')
  if (result === 'js' || result === 'javascript') return 'jsx'
  if (result === 'scss') return 'text/x-scss'
  if (result === 'less') return 'text/x-less'
  return result
}

Link to code

Down the road, more changes will be necessary to allow syntax highlighting for other languages such as "Ruby" for instance.

What do you think?

meebix on 12 Sep 2018

👍6

can we reopen this?

GiancarlosIO on 8 Jan 2019

👍2

Yeah can we reopen this?

drewlustro on 7 Jun 2019

👍3

Ya please reopen. Outside of JS/React other languages do not work. For example I'm struggling to get Dart code highlighted.

pavanpodila on 12 Dec 2019

Hey all,

The recommended way to get better syntax highlighting support outside of playground is to use gatsby-remark-vscode. It has much more support for languages than prism, doesn't need any javascript, and makes adding languages easy.

Please check out https://github.com/doczjs/docz/tree/master/examples/with-gatsby-remark-vscode for a complete example.