feat(v2): Improve the initial templates

[stevenhansel]

Motivation

The main motivation is to improve the contents of the initial templates. It's issued at #4079 that the initial templates should be a "small" representative of a real documentation site and show real content instead of lorem ipsum.

Current Progress:

• Add a getting started documentation on Docusaurus.
• Add a documentation on Markdown Features.
• Add a small documentation on how to create a page, documentation, and post.
• Add a thank you doc, which contains What's next? that suggests the user some actions related to Docusaurus itself.
• Removed the initial docs from the classic template.

Future Plans:

• Add more content and improve the styling of the index page

Related Contributors

• @besemuna is working on the "extras" part of the initial templates.

Have you read the Contributing Guidelines on pull requests?

Yes.

Test Plan

(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!)

Related PRs

(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.)

[netlify]

[V1] Deploy preview success

Built with commit a0bd2d5

https://deploy-preview-4302--docusaurus-1.netlify.app

[netlify]

Deploy preview for docusaurus-2 ready!

Built with commit a0bd2d5

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

[github-actions]

⚡️ Lighthouse report for the changes in this PR:

Category	Score
🟢 Performance	90
🟢 Accessibility	96
🟢 Best practices	100
🟢 SEO	100
🟢 PWA	95

Lighthouse ran on https://deploy-preview-4302--docusaurus-2.netlify.app/classic/

[github-actions]

Size Change: -46 B (0%)

Total Size: 532 kB

Filename	Size	Change
website/build/assets/css/styles.********.css	87.1 kB	-46 B (0%)

ℹ️ View Unchanged

Filename	Size	Change
website/build/assets/js/main.********.js	359 kB	0 B
website/build/blog/2017/12/14/introducing-docusaurus/index.html	60.3 kB	0 B
website/build/docs/introduction/index.html	235 B	0 B
website/build/index.html	25.4 kB	0 B

_{compressed-size-action}

[slorber]

Thanks, that's a good start.

I made some suggestions, particularly about the docs we may want.

For this PR I think you could just work on the first part (not the Extras category), so that we can merge it before everything is done?

[slorber]

I suggest we could use the following docs/sidebar:

module.exports = {
  docs: {
    "Docusaurus Tutorial": [
      "Docusaurus Intro", // Basic infos + install steps
      "Create a doc", // + how to add it to  the sidebar
      "Create a page", // jsx + md
      "Create a post",
      "Markdown Features", // basic markdown + some MDX explanations
      "Thank you" // end of tutorial, show what's next?
    ],
    Extras: [
      "Deploy your site", // configure a bit + build + deploy to GH pages?
      "Translate your site", // very basic version, like add "fr" language + put a copy `docs/intro.md` to `i18n/fr/plugin-docs/intro.md` + run `yarn start --locale fr`
      "Manage versions" // just run the versioning cli + restart the site with yarn start
    ]
  }
};

Does it make sense to you?

Maybe it's too much doc, don't know, we may remove some sections from the Extras category?

[stevenhansel]

Yes, thank you for giving me out this overall structure. I already put some work in the Docusaurus Tutorial part and I think there are too many things in the Markdown Features right now, maybe we can like include some examples in Create a doc section and then for the details we can refer to the main documentation site?

For the Extras part, I think Translate your site is a little bit too specific (this is pretty subjective), we can just refer to the main docs.

[lex111]

@ShinteiMai so we need to close this PR in favor of #4320?

[stevenhansel]

@ShinteiMai so we need to close this PR in favor of #4320?

Most likely, yes. From what @slorber said, the template structure is this:

module.exports = {
  docs: {
    "Docusaurus Tutorial": [
      "Docusaurus Intro", // Basic infos + install steps
      "Create a doc", // + how to add it to  the sidebar
      "Create a page", // jsx + md
      "Create a post",
      "Markdown Features", // basic markdown + some MDX explanations
      "Thank you" // end of tutorial, show what's next?
    ],
    Extras: [
      "Deploy your site", // configure a bit + build + deploy to GH pages?
      "Translate your site", // very basic version, like add "fr" language + put a copy `docs/intro.md` to `i18n/fr/plugin-docs/intro.md` + run `yarn start --locale fr`
      "Manage versions" // just run the versioning cli + restart the site with yarn start
    ]
  }
};

This PR #4302 is focused at the "docs" part, which is the main content of the initial templates, and #4320 is the "extras" part.

[lex111]

@ShinteiMai can you both (cc @besemuna) split the changes in your PRs so we can merge these ones, and your efforts were credited?

[stevenhansel]

@ShinteiMai can you both (cc @besemuna) split the changes in your PRs so we can merge these ones, and your efforts were credited?

Sure, I will edit the description of this PR and cc him

[slorber]

Thanks, that looks like a great improvement compared to the previous version already!

I think your text is too verbose and you add too much details, this should really be something minimalistic.

Remember the user will read the real doc in the end if he's convinced so we don't have to show him all the features.

Does it make sense?

I may be wrong, just expressing my opinions