Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

feat(v2): allow users to specify a custom ssr HTML template #3387

Merged
merged 2 commits into from
Sep 2, 2020
Merged

feat(v2): allow users to specify a custom ssr HTML template #3387

merged 2 commits into from
Sep 2, 2020

Conversation

mpsq
Copy link
Contributor

@mpsq mpsq commented Sep 1, 2020

Motivation

This PR adds a new property to docusaurus.config.js so the users can specify their own SSR HTML template:

docusaurus.config.js:

module.exports = {
  ...
  ssrTemplate,
  ...
}

Where ssrTemplate is a string, such as:

const ssrTemplate = `<!DOCTYPE html>
<html <%~ it.htmlAttributes %>>
  <head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=0.86, maximum-scale=3.0, minimum-scale=0.86">
    <meta name="generator" content="Docusaurus v<%= it.version %>">
    <%~ it.headTags %>
    <% it.metaAttributes.forEach((metaAttribute) => { %>
      <%~ metaAttribute %>
    <% }); %>
  </head>
  <body <%~ it.bodyAttributes %>>
    <%~ it.preBodyTags %>
    <div id="__docusaurus main-wrapper">
      <%~ it.appHtml %>
    </div>
    <%~ it.postBodyTags %>
  </body>
</html>`;

This is tested and works as a PoC, if the Docusaurus team wants to process further, I am happy to implement tests + write the corresponding documentation.

Have you read the Contributing Guidelines on pull requests?

Yes.

Test Plan

Not implemented yet - validating the concept first.

@mpsq mpsq requested a review from yangshun as a code owner September 1, 2020 19:23
@facebook-github-bot facebook-github-bot added the CLA Signed Signed Facebook CLA label Sep 1, 2020
@docusaurus-bot
Copy link
Contributor

Deploy preview for docusaurus-2 failed.

Built with commit 27e4f32

https://app.netlify.com/sites/docusaurus-2/deploys/5f4e9f9d50b92f0008a0b867

@docusaurus-bot
Copy link
Contributor

docusaurus-bot commented Sep 1, 2020 •
edited
Loading

Deploy preview for docusaurus-2 ready!

Built with commit c76b498

https://deploy-preview-3387--docusaurus-2.netlify.app

@slorber
Copy link
Collaborator

slorber commented Sep 2, 2020

Hi,

What is the true motivation behind this feature? implement the defer mode (#3237) asap?

I'm not against, but what is annoying me is that this expose additional internals, like the variables we pass to the template etc, that now become part of the API surface. If we ship this, I don't want to guarantee that we won't ever refactor this template, so the users using it expose themselves to potential breaking changes, and I'd rather not have to maintain the doc of this API contract. So basically the idea is: if you do use this feature, you are on your own and you should know what you are doing.

@mpsq
Copy link
Contributor Author

mpsq commented Sep 2, 2020 •
edited
Loading

In my scenario, I would like to:

  • Change attributes on body, I want my website to be schema.org compatible
  • Change the viewport meta
  • Change the way scripts are loaded (with defer)
  • Hardcode other metas (React Helmet is most of the time an overkill with downsides)

This only way to do this kind of modification is by having access to the template. I can also imagine a scenario where a user would like to maintain a div outside __docusaurus for 3rd party cookie consent banner for example.
This would expose the user to Docusaurus internals, but as you said this is an advanced usage. I can see the default template changing, but never to a point where it would require more than a few minutes to backport the changes.

@slorber
Copy link
Collaborator

slorber commented Sep 2, 2020

Thanks @mpsq , let's make this happen.

Agree that it shouldn't be hard to backport, and it's quite similar to swizzling anyway.

Can you add some doc with a warning explaining all that?

If you find a way to test it, that'd be nice too

@mpsq
Copy link
Contributor Author

mpsq commented Sep 2, 2020 •
edited
Loading

I added the documentation in the last commit.

Regarding the tests, I had a look and there is nothing obvious that can be done with unit tests. A good solution to this problem might be to use integration tests: running a webpack (server, not client) against a "dummy" (most likely stripped down) config and check the output. The downside is that it will take time for webpack to compile the code. This will definitely impact the time it takes to run the tests suite. What do you think, should I try to go down that route?

@slorber
Copy link
Collaborator

slorber commented Sep 2, 2020

Thanks, that seems fine to me.

I also don't see a good way to test this easily

@slorber slorber added the pr: new feature This PR adds a new API or behavior. label Sep 2, 2020
@slorber slorber merged commit 3ace600 into facebook:master Sep 2, 2020
@mpsq mpsq deleted the mp-ssr-template branch September 2, 2020 17:30
@slorber
Copy link
Collaborator

slorber commented Sep 3, 2020

Released in alpha 63 🎊 please spread the word 🙏 and tell me if this works fine for you
https://twitter.com/docusaurus/status/1301562737693138944
https://github.com/facebook/docusaurus/releases/tag/v2.0.0-alpha.63

@mpsq
Copy link
Contributor Author

mpsq commented Sep 3, 2020

Thanks @slorber! 🎉
I already pushed the new custom template. It all works nicely 👍 .

@nebrelbug
Copy link
Contributor

@slorber we may want to mention that the template is Eta syntax, not EJS or lodash.template or doT, so people don't get confused 🤔

@yangshun
Copy link
Contributor

yangshun commented Sep 7, 2020

We may want to mention that the template is Eta syntax, not EJS or lodash.template or doT, so people don't get confused

I agree

@slorber
Copy link
Collaborator

slorber commented Sep 7, 2020

Yes, @mpsq do you want to improve a bit the doc?

@mpsq
Copy link
Contributor Author

mpsq commented Sep 7, 2020

Sure, I will have a look ;)

@mpsq mpsq mentioned this pull request Sep 9, 2020
Merged
@mpsq
Copy link
Contributor Author

mpsq commented Sep 9, 2020

#3425

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@yangshun yangshun Awaiting requested review from yangshun

Assignees
No one assigned
Labels
CLA Signed Signed Facebook CLA pr: new feature This PR adds a new API or behavior.
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
6 participants
@mpsq @docusaurus-bot @slorber @nebrelbug @yangshun @facebook-github-bot