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

feat(v2): Improve the initial templates #4302

Merged
merged 14 commits into from
Mar 12, 2021
Merged
203 changes: 0 additions & 203 deletions packages/docusaurus-init/templates/classic/docs/doc1.md

This file was deleted.

6 changes: 0 additions & 6 deletions packages/docusaurus-init/templates/classic/docs/doc2.md

This file was deleted.

14 changes: 0 additions & 14 deletions packages/docusaurus-init/templates/classic/docs/doc3.md

This file was deleted.

71 changes: 71 additions & 0 deletions packages/docusaurus-init/templates/classic/docs/gettingStarted.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
---
id: getting-started
stevenhansel marked this conversation as resolved.
Show resolved Hide resolved
title: Getting Started
slug: /
---

import TOCInline from '@theme/TOCInline';
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

This page will help you to get started with the development process of your Docusaurus project.


## Setting up the development environment

If you haven't setup your development environment. Let's go through a small step-by-step tutorial to get started with your Docusaurus project.

:::note
stevenhansel marked this conversation as resolved.
Show resolved Hide resolved
Feel free to edit this page as you follow the tutorial!
:::

### Step 1: Generate a Docusaurus site

Let's run a command to generate the classic template. You can run this command anywhere either in a new empty repository or within an existing repository.

```shell
npx @docusaurus/init@latest init my-documentation classic
```

### Step 2: Install Dependencies
stevenhansel marked this conversation as resolved.
Show resolved Hide resolved

Don't forget to install the dependencies required, run the install command from your preferred package manager in the root directory of the project:

<Tabs
defaultValue="npm"
values={[
{ label: 'npm', value: 'npm' },
{ label: 'Yarn', value: 'yarn' },
]}
>
<TabItem value="npm">

```shell
npm install
```

</TabItem>
<TabItem value="yarn">

```shell
yarn
```

</TabItem>
</Tabs>

### Step 3: Start your Docusaurus site

Run this command to start the Docusaurus development server and start developing by adding content to your docusaurus project:

```shell
npx docusaurus start
```

Open up `gettingStarted.md` in your project folder and try to edit some lines. The site should reload automatically after you save your changes.

### That's it!

Congratulations! You've successfully run and modified your Docusaurus project.


Original file line number Diff line number Diff line change
Expand Up @@ -38,13 +38,9 @@ module.exports = {
title: 'Docs',
items: [
{
label: 'Style Guide',
label: 'Getting Started',
to: 'docs/',
},
{
label: 'Second Doc',
to: 'docs/doc2/',
},
],
},
{
Expand Down
2 changes: 1 addition & 1 deletion packages/docusaurus-init/templates/classic/sidebars.js
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
module.exports = {
someSidebar: {
Docusaurus: ['doc1', 'doc2', 'doc3'],
Docusaurus: ['getting-started'],
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Features: ['mdx'],
},
};