Docusaurus: Allow setting scripts and styles for a specific pages.

[nicolo-ribaudo]

Is this a bug report?

No, it is a feature request.

Have you read the Contributing Guidelines?

Yup

Feature request description

While working on using Docusaurus for the Babel website, the only way I could find of importing some scripts/styles only in one specific page was to directly write <script and <link in the react component for that page. (https://github.com/babel/website/pull/1533/files#diff-f2407366091d2ef0cf6645254d421ab0)

I propose an option to specify them in siteConfig.js. I came up with two ideas:

({
  //...
  scripts: {
    "*": [ "file/included.js", "in/every/page.js" ],
    "repl": [ "file/only", "included/in/the/repl/page.js" ]
  },
});

({
  // ...
  scripts: [
    { page: "repl", url: "file/included/in/repl.js" },
    "included/in/every/page.js",
  ]
});

Personally I prefer the second, since it can be extended in the future with flags like async: boolean or position: "head" | "body".

---

If this FR gets accepted, I can work on a pull request.

[JoelMarcey]

Hi @nicolo-ribaudo -- would love to see a PR around this. I think I like the second way better as well, although I think it would need to be documented more clearly than the first way.

[zenflow]

Actually, isn't it pretty easy to accomplish this already?

Example: https://github.com/babel/website/blob/master/website/pages/en/repl.js

If so, then I think documentation is the only issue

[zenflow]

As is, I think I'd personally prefer to use the pattern in the example (below) over the proposed API..

const styles = [/* ... */]
const scripts = [/* ... */]

module.exports = props => (
  <div>
    {styles.map(url => <link rel="stylesheet" href={url} key={url} />)}
    // ...
    {scripts.map(url => <script src={url} key={url} />)}
  </div>
)

because that info is co-located with the html content it goes with _and_ it's much simpler.

[JoelMarcey]

@zenflow - good idea, I think. And there would be no change to the Docusaurus core nor a new config option. But documenting it would be key, like you said.

@nicolo-ribaudo Do you agree?

@zenflow (or @nicolo-ribaudo) would you be willing to submit a PR to add the documentation for how to do this?

[zenflow]

Sure, I'd be happy to add @nicolo-ribaudo's pattern to the documentation.

I'll go ahead once we all agree

[nicolo-ribaudo]

Well, I don't remember why I tought that how I did it wasn't enough :sweat_smile:
I'm ok with updating the docs.

[zenflow]

Actually one question - what about API symmetry?

If we all agree that its easy enough to render the <script> or <link> tags yourself, and for global scripts this can be done in the Footer.js, then why do we need siteConfig.scripts? I think siteConfig.stylesheets is necessary so that those resources will be loaded before the html content, but it seems like the siteConfig.scripts isn't needed. No idea what if anything the maintainers would want to do about that, given that it's already in the v1.0 API. Is it worth planning to remove in the next major?

[JoelMarcey]

@zenflow I kinda see what you are saying. But I think it is ok for global scripts to have two options - the siteConfig.js option (which I like better because it is more easily exposed and visible) and you could, in a note, say you could also add scripts in Footer.js as well. The thing about just allowing Footer.js scripts for global scripts is what happens if someone removes Footer.js because they don't want it. Having it in siteConfig.js still allows them to do that.

[yangshun]

@zenflow Would you like to add update the docs?

[endiliey]

Current pattern suggested above works really well in current version. In next version we are using react-helmet under the hood and will be providing Head / Helmet component and basically you can do it on every pages that you'll need.

Closing this up due to stale activity as well

[talisonfc]

I created a 'script' folder inside static, and I added the path 'script/filename.js' in scripts array on siteConfig.js

My static folder:

• static
  
  
  
  • css
  
  
  • img
  
  
  • script:
    
    
    
    
    
    • index.js
    
    
    
  
  

scripts: ['https://buttons.github.io/buttons.js', "scripts/index.js"]

[endiliey]

you should append the baseurl

so /scripts/index.js

[yangshun]

You should append the baseUrl yourself. Reason being we may want to allow scripts that are not from the build directory.