Playground-local stylesheets #290

derekstavis · 2018-09-04T22:40:08Z

Hey 👋

I'm migrating the docs from Vanilla Form, my form state/validation management library. Currently I'm using Styleguidist, so migrating to Docz is pretty easy as all documentation and examples are already in Markdown.

Background

As the documentation examples are using plain HTML elements, I've used Styleguidist's require configuration option to apply Milligram styles for better-looking components in playground. This basically requires applies Milligram globally in the docs page.

For the Docz migration I followed the same idea, but using the CSS plugin to achieve it. I could make it work and all playground examples now have Milligram styles, but as a side-effect, Docz theme is completely screwed up, as Milligram uses global CSS.

Playground Isolation

I like a lot that both Styleguidist and Docz render playgrounds inline (no funky iframes), even understanding that conflicts ranging from HTML IDs to CSS could happen. On the other hand, I've come to believe that having at least styles isolation inside playgrounds is an important thing, because not all libraries are using fancy CSS systems (emotion, styled, css-modules, ...), so their styles could interfere with Docz's own theme.

Possible solution

Trying to avoid using iframe, it seems that Shadow DOM could be a thing here. By Shadow DOM-ing playground's preview and injecting style tags inside the playground we could get the desired styles isolation.

EDIT:: After some tinkering, I came with this component to Shadow DOM the example. The only downside is that it breaks HTML preview (for obvious reasons):

import React from 'react'
import ShadowDOM from 'react-shadow'
import marx from 'marx-css/css/marx.css'

const Themed = ({children}) =>
  <ShadowDOM include={[marx]}><div>{children}</div></ShadowDOM>

export default Themed

I had to match \.css$ and use file-loader in the pipeline to achieve the desired effect.

Even if this is already sufficient for me, having to repeat the theme wrapper every demo makes the demos clunky.

The text was updated successfully, but these errors were encountered:

pedronauck · 2018-09-06T17:55:43Z

Hey @derekstavis you can use the new htmlContext that's doesn't document yet on our docz 🙄But is very simple and should fix your problem:

export default {
  htmlContext: {
    head: {
      links: [{ rel: 'stylesheet', href: '/path/of/your/css' }]
    }
  }
}

You can see more info about HtmlContext here: https://github.com/pedronauck/docz/blob/master/packages/docz-core/src/commands/args.ts#L27-L40

Dobby89 · 2018-09-11T19:44:09Z

@pedronauck Could you please expand on how this htmlContext is used?

I've updated my doczrc.js config as follows, but I'm getting a 404 response for the CSS when I load the page GET http://localhost:3000/build/main.css 404 (Not Found)

doczrc.js

export default {
    indexHtml: './src/documentation/index.html',
    htmlContext: {
        head: {
            links: [
                { rel: 'stylesheet', href: '/build/main.css' }
            ]
        }
    }
};

./src/documentation/index.html

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <meta name="description" content="{{ description }}">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta http-equiv="X-UA-Compatible" content="ie=edge">
    <title>{{ title }}</title>
    {{ head }}
  </head>
  <body>
    <div id="root" />
    {{ footer }}
  </body>
</html>

donifer · 2018-09-12T00:36:17Z

@pedronauck I believe the issue he is mentioning is applying the css only to the previewer.

I could make it work and all playground examples now have Milligram styles, but as a side-effect, Docz theme is completely screwed up, as Milligram uses global CSS.

So he is able to load the styles globally but it messes up the Docz theme itself. Is there a workaround for that?

Emiliano-Bucci · 2018-11-06T22:15:23Z

@donifer Hi, i'm also getting the same error (404) when trying to append a custom .css file. htmlContext: { head: { links: [{ rel: "stylesheet", href: "./style.css" }] } }

Maybe i'm putting the css file in the wrong place? I put it along with the doczrc.js file

pedronauck · 2018-11-07T12:46:31Z

@pedronauck I believe the issue he is mentioning is applying the css only to the previewer.

I could make it work and all playground examples now have Milligram styles, but as a side-effect, Docz theme is completely screwed up, as Milligram uses global CSS.

So he is able to load the styles globally but it messes up the Docz theme itself. Is there a workaround for that?

@donifer, what you can do is pass some class just to playground, but some css that just act in the playground isn't possible 😕

Emiliano-Bucci · 2018-11-07T12:51:56Z

@pedronauck So even a global style.css isn't possible? Or at least, style the html? Maybe add some custom styles like fonts, colors, etc

pedronauck · 2018-11-07T13:03:34Z

You can put styles using htmlContext, but the public url need to be .docz/public. But I'm seeing that this is with a bug now, I'm fixing it and making a new release!

Emiliano-Bucci · 2018-11-07T13:05:00Z

Ok, thank you very much! :)

liuzhiyang0113 · 2018-11-19T12:22:04Z

i also get 404.

  htmlContext: {
    head: {
      links: [
        {
          rel: 'stylesheet',
          href: './index.css'
        }
      ],
      raw: [
        '<style>html{font-size:50px;}</style>'
      ]
    }
  }

index.css is in the root directory

Dobby89 · 2018-12-14T08:44:08Z

@pedronauck Do you have any objection to using iframes to load each Playground? I see this issue coming up quite often and iframes seem to be the way to go for similar component docs generator tools.

Without style isolation, there's no way to safely use Docz.

pedronauck · 2018-12-14T10:32:35Z

@Dobby89 I don't have any objections, to be honest, I really think is the best solution since with an iframe we can simulate viewport and be able to work more effectively with responsive queries. But, I tried to transform playground render using iframes, but I didn't get success. I'll try again on v1.

giulianok · 2019-02-06T21:12:51Z

You can do the following in case you don't want to commit .docz (since has tmp folders)

import fs from "fs";

export default {
  typescript: true,
  htmlContext: {
    head: {
      raw: `<style>${fs.readFileSync(
        process.cwd() + "/src/assets/demo.css"
      )}</style>`
    }
  }
};

eazy-g · 2019-03-15T16:33:52Z

@giulianok That's useful, thanks. Now I'm stuck by docz overriding the styles I inlined, since the styles added to 'htmlContext' become the first style tag in the document...any ideas?

Specifically, I'm attempting to define the font-family for the document, and docz is overriding it as Source Sans Pro in a later style tag

pedronauck closed this as completed Sep 6, 2018

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Playground-local stylesheets #290

Playground-local stylesheets #290

derekstavis commented Sep 4, 2018 •

edited

Loading

pedronauck commented Sep 6, 2018 •

edited

Loading

Dobby89 commented Sep 11, 2018 •

edited

Loading

donifer commented Sep 12, 2018

Emiliano-Bucci commented Nov 6, 2018

pedronauck commented Nov 7, 2018

Emiliano-Bucci commented Nov 7, 2018

pedronauck commented Nov 7, 2018

Emiliano-Bucci commented Nov 7, 2018

liuzhiyang0113 commented Nov 19, 2018

Dobby89 commented Dec 14, 2018 •

edited

Loading

pedronauck commented Dec 14, 2018

giulianok commented Feb 6, 2019

eazy-g commented Mar 15, 2019

Playground-local stylesheets #290

Playground-local stylesheets #290

Comments

derekstavis commented Sep 4, 2018 • edited Loading

Background

Playground Isolation

Possible solution

pedronauck commented Sep 6, 2018 • edited Loading

Dobby89 commented Sep 11, 2018 • edited Loading

donifer commented Sep 12, 2018

Emiliano-Bucci commented Nov 6, 2018

pedronauck commented Nov 7, 2018

Emiliano-Bucci commented Nov 7, 2018

pedronauck commented Nov 7, 2018

Emiliano-Bucci commented Nov 7, 2018

liuzhiyang0113 commented Nov 19, 2018

Dobby89 commented Dec 14, 2018 • edited Loading

pedronauck commented Dec 14, 2018

giulianok commented Feb 6, 2019

eazy-g commented Mar 15, 2019

derekstavis commented Sep 4, 2018 •

edited

Loading

pedronauck commented Sep 6, 2018 •

edited

Loading

Dobby89 commented Sep 11, 2018 •

edited

Loading

Dobby89 commented Dec 14, 2018 •

edited

Loading