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.

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

Improve the initial templates #4079

Closed
slorber opened this issue Jan 20, 2021 · 2 comments · Fixed by #4320
Closed

Improve the initial templates #4079

slorber opened this issue Jan 20, 2021 · 2 comments · Fixed by #4320
Labels
feature This is not a bug or issue with Docusausus, per se. It is a feature request for the future. mlh Major League Hacking Fellowship status: claimed Issue has been claimed by a contributor who plans to work on it.

Comments

@slorber
Copy link
Collaborator

slorber commented Jan 20, 2021

🚀 Feature

We want to give a good impression to users when they first try Docusaurus, and improve:

  • our init templates (generated with the CLI)
  • the new.docusaurus.io CodeSandbox experience (sync with the classic template).

It was proposed (#3489) that we make the initial docs more representative of a real-world doc site and be a bit more opinionated:

  • be more like a small example site rather than a hello-world empty site
  • apply documentation best practices (docs vs apis)
  • show real content instead of lorem ipsum
  • use more markdown features to showcase the features of Docusaurus (maybe this can even be kept in sync with the markdown features category of Docusaurus site itself)

We also have some content duplication in templates, as each template MD docs are very similar and copy/paste. We should find a way to create once this content for all sites instead of keeping them in sync manually.

For users that really want an empty/minimal Docusaurus site, we could add a new separate minimalistic template.

@slorber slorber added feature This is not a bug or issue with Docusausus, per se. It is a feature request for the future. status: needs triage This issue has not been triaged by maintainers labels Jan 20, 2021
@slorber slorber added status: claimed Issue has been claimed by a contributor who plans to work on it. mlh Major League Hacking Fellowship and removed status: needs triage This issue has not been triaged by maintainers labels Jan 21, 2021
@javidrashid
Copy link
Contributor

javidrashid commented Feb 17, 2021

Fellows to document what would be the good UI. You can come up with a general meaningful UI with minimum content, links and submit a PR for review.

General guidelines:

  1. Look a the existing features and come up with the best experience as you.
  2. How init template can be improved.
  3. Redesign the existing template. (UI/UX).

There is another feature were we need to build a template corresponding to a particular theme like Bootstrap, Tailwind. This issue can serve as a precursor for that task.

@slorber
Copy link
Collaborator Author

slorber commented Feb 26, 2021

The idea for me would to be create a minimalistic documentation site for Docusaurus site itself, so that it kind of serve as a realistic example.

We want to spark immediate joy to the user and let him try Docusauurs in a step by step guide where each action provides immediate gratification by seeing the result of the action.

I don't think the user needs to understand everything about Docusaurus at the end of this tutorial, but be convinced that this is a powerful tool and quite simple to use.

What about using 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
    ]
  }
};

I suggest the initial PR (#4302) focus first on the "Docusaurus tutorial" category. Once it's merged we can add the Extras category later?

Do you think this is a good structure?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
feature This is not a bug or issue with Docusausus, per se. It is a feature request for the future. mlh Major League Hacking Fellowship status: claimed Issue has been claimed by a contributor who plans to work on it.
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants