Join GitHub today
GitHub is home to over 40 million developers working together to host and review code, manage projects, and build software together.Sign up
change(v2): swap init parameter order for name and template #1720
Swap init command order for template and project name.
Previously our init command was
$ init [name] [template]
So in the doc we exemplify as
$ npx @docusaurus/init@next init my-website classic
This is not too bad. But we also accept git url for template, in which case the template argument will be very long and people will nearly certainly copy and paste.
$ npx @docusaurus/init@next init [name] https://github.com/wgao19/docusaurus-template-no-style.git
Then having template as the last argument is not as friendly as having it before the project name because people can copy and paste the whole thing and input a project name.
$ npx @docusaurus/init@next init https://github.com/wgao19/docusaurus-template-no-style.git [name]
Have you read the Contributing Guidelines on pull requests?
(Write your test plan here. If you changed any code, please provide us with clear instructions on how you verified your changes work. Bonus points for screenshots and videos!)
(If this PR adds or changes functionality, please take some time to update the docs at https://github.com/facebook/docusaurus, and link to your PR here.)
Deploy preview for docusaurus-2 ready!
Built with commit 7488037
Deploy preview for docusaurus-preview ready!
Built with commit 7488037
yangshun left a comment
Hmm I'm not so sure whether it's a good idea to change the order now. But if we were to change it, we should do it asap. There's also value in doing it in a similar fashion as Gatsby: https://www.gatsbyjs.org/docs/starters/
Alternatively, make some of the parameters into options so that the order wouldn't matter, we can default the template to our classic template.
Will defer to @endiliey to make the call.
endiliey left a comment
actually tbh i feel there isnt a lot of benefit of changing the order now.
in fact: it broke the order for previous version (some people can just remove the @next and later find that the order is different for previous version
and also if both options are not passed, we still prompt for name first and then template.
im thinking to maybe lets just revamp the init once and for all
simplify it to
npx @docusaurus/init then interactively prompt ?? or default the name and template to website and classic
I agree with this, please keep this behavior. But please do not remove the default CLI command argument option. The brevity of just one copy and paste and be done with it is unparalleled.
Let me rephrase properly what I mean regarding the benefit of swapping the order:
Currently, we instruct people to initialize project like this
This is OK since they're both optional and the template
However, if we want to promote initializing projects from git repo, the behavior becomes:
People cannot copy and paste this string directly because there is a
Then they'd have to copy the first section
Then type their project name or whatever,
then copy and paste the git repo
I think the "a lot of benefit" is rather subjective.. it's whether we want to promote the behavior of using repo as template. If we do want that, the difference is very non trivial. Just try it, you copy and paste twice, tab in and out of your terminal, it's ridiculous.
Gatsby's command takes URL in middle doesn't mean it's the best experience.
However, I'm OK with closing this issue because currently both of you are against it. And I'm not very familiar with CLI development so I think I'm not the best person to make the call. I'll thereby close this issue to let you guys plan things properly.