feat(v2): Improve the initial templates #4302 (#4320)

* feat: add getting started doc at classic inital templates

* fix: improve the contents of getting started page

* fix: fix slug routing

* fix: rename gettingStarted to getting-started and re-adjust the content

* feat: add markdown-features docs

* feat: add a page on how to create a simple document

* feat: add a page on how to create pages

* feat: add create a post doc

* feat: add thank you page with whats next

* feat : update sidebar.js

* feat : add introduction content

* feat : add self hosting content

* feat : add GitHub pages content

* fix : remove automatically deploying with github actions content

* feat : add deploying to netlify

* feat : add Translate your site

* add : Manage versions

* fix : formatted docs with prettier

* Revert "fix : formatted docs with prettier"

This reverts commit af8c0b48

* run prettier to init templates with fixes

* complete new init template

* rename manage-docs-versions

* change wording

* refresh config file

* rework init template homepage

* minor changes

Co-authored-by: Lisa Chandra <52909743+lisa761@users.noreply.github.com>
Co-authored-by: Javid <singularity.javid@gmail.com>
Co-authored-by: ShinteiMai <stevenhanselgo@gmail.com>
Co-authored-by: slorber <lorber.sebastien@gmail.com>

.prettierignore

@@ -10,5 +10,4 @@ packages/docusaurus-*/lib/*
 packages/docusaurus-1.x/lib/core/metadata.js
 packages/docusaurus-1.x/lib/core/MetadataBlog.js
 packages/docusaurus-*/lib-next/
-packages/docusaurus-init/templates/**/*.md
 __fixtures__

packages/docusaurus-init/templates/classic/docs/congratulations.md

@@ -0,0 +1,19 @@
+---
+title: Congratulations!
+---
+
+Congratulations on making it this far!
+
+You have learned the **basics of Docusaurus** and made some changes to the **initial template**.
+
+Docusaurus has **much more to offer**!
+
+Have 5 more minutes? Take a look at **[versioning](./manage-docs-versions.md)** and **[i18n](./translate-your-site.md)**.
+
+## What's next?
+
+- Read the [official documentation](https://v2.docusaurus.io/).
+- Add a custom [Design and Layout](https://v2.docusaurus.io/docs/styling-layout)
+- Add a [search bar](https://v2.docusaurus.io/docs/search)
+- Find inspirations in the [Docusaurus showcase](https://v2.docusaurus.io/showcase)
+- Get involved in the [Docusaurus Community](https://v2.docusaurus.io/community/support)

packages/docusaurus-init/templates/classic/docs/create-a-blog-post.md

@@ -2,7 +2,7 @@
 title: Create a Blog Post
 ---
 
-This page will help you on how to create blog posts in Docusaurus.
+Docusaurus creates a **page for each blog post**, but also a **blog index page**, a **tag system**, an **RSS** feed...
 
 ## Create a Blog Post
 
@@ -15,6 +15,7 @@ author: Steven Hansel
 author_title: Docusaurus Contributor
 author_url: https://github.com/ShinteiMai
 author_image_url: https://github.com/ShinteiMai.png
+tags: [greetings]
 ---
 
 Congratulations, you have made your first post!

packages/docusaurus-init/templates/classic/docs/create-a-document.md

@@ -2,7 +2,7 @@
 title: Create a Document
 ---
 
-Documents are pages with a **sidebar**, a **previous/next navigation** and many other useful features.
+Documents are a **group of pages** connected through a **sidebar**, a **previous/next navigation** and **versioning**.
 
 ## Create a Document
 

packages/docusaurus-init/templates/classic/docs/create-a-page.md

@@ -2,7 +2,7 @@
 title: Create a Page
 ---
 
-Any React or Markdown file created under `src/pages` directory is converted into a website page:
+Add **Markdown or React** files to `src/pages` to create **standalone pages**:
 
 - `src/pages/index.js` -> `localhost:3000/`
 - `src/pages/foo.md` -> `localhost:3000/foo`

packages/docusaurus-init/templates/classic/docs/deploy-your-site.md

@@ -0,0 +1,27 @@
+---
+title: Deploy your site
+---
+
+Docusaurus is a **static-site-generator** (also called [Jamstack](https://jamstack.org/)), and builds your site as **static HTML, JavaScript and CSS files**.
+
+## Build your site
+
+Build your site **for production**:
+
+```bash
+npm run build
+```
+
+The static files are generated in the `build` directory.
+
+## Deploy your site
+
+Test your production build locally:
+
+```bash
+npm run serve
+```
+
+The `build` folder is now served at `http://localhost:3000/`.
+
+You can now deploy the `build` folder **almost anywhere** easily, **for free** or very small cost (read the **[Deployment Guide](https://v2.docusaurus.io/docs/deployment)**).

packages/docusaurus-init/templates/classic/docs/getting-started.md

@@ -3,17 +3,21 @@ title: Getting Started
 slug: /
 ---
 
-## Step 1: Generate a new Docusaurus site
+Get started by **creating a new site**
 
-If you haven't already, generate a new Docusaurus site using the classic template:
+Or **try Docusaurus immediately** with **[new.docusaurus.io](https://new.docusaurus.io)** (CodeSandbox).
+
+## Generate a new site
+
+Generate a new Docusaurus site using the **classic template**:
 
 ```shell
 npx @docusaurus/init@latest init my-website classic
 ```
 
-## Step 2: Start your Docusaurus site
+## Start your site
 
-Run the development server in the newly created `my-website` folder:
+Run the development server:
 
 ```shell
 cd my-website
@@ -21,8 +25,6 @@ cd my-website
 npx docusaurus start
 ```
 
-Open `docs/getting-started.md` and edit some lines. The site reloads automatically and display your changes.
+Your site starts at `http://localhost:3000`.
 
-## That's it!
-
-Congratulations! You've successfully run and modified your Docusaurus project.
+Open `docs/getting-started.md` and edit some lines: the site **reloads automatically** and display your changes.

packages/docusaurus-init/templates/classic/docs/manage-docs-versions.md

@@ -0,0 +1,53 @@
+---
+title: Manage Docs Versions
+---
+
+Docusaurus can manage multiple versions of your docs.
+
+## Create a docs version
+
+Release a version 1.0 of your project:
+
+```bash
+npm run docusaurus docs:version 1.0
+```
+
+The `docs` directory is copied into `versioned_docs/version-1.0` and `versions.json` is created.
+
+Your docs now have 2 versions:
+
+- `1.0` at `http://localhost:3000/docs/` for the version 1.0 docs
+- `current` at `http://localhost:3000/docs/next/` for the **upcoming, unreleased docs**
+
+## Add a Version Dropdown
+
+To navigate seamlessly across versions, add a version dropdown.
+
+Modify the `docusaurus.config.js` file:
+
+```js title="docusaurus.config.js"
+module.exports = {
+  themeConfig: {
+    navbar: {
+      items: [
+        // highlight-start
+        {
+          type: 'docsVersionDropdown',
+        },
+        // highlight-end
+      ],
+    },
+  },
+};
+```
+
+The docs version dropdown appears in your navbar:
+
+![Docs Version Dropdown](/img/tutorial/docsVersionDropdown.png)
+
+## Update an existing version
+
+It is possible to edit versioned docs in their respective folder:
+
+- `versioned_docs/version-1.0/hello.md` updates `http://localhost:3000/docs/hello`
+- `docs/hello.md` updates `http://localhost:3000/docs/next/hello`

packages/docusaurus-init/templates/classic/docs/markdown-features.mdx

@@ -2,11 +2,11 @@
 title: Markdown Features
 ---
 
-Docusaurus supports the [Markdown](https://daringfireball.net/projects/markdown/syntax) syntax and has some additional features.
+Docusaurus supports **[Markdown](https://daringfireball.net/projects/markdown/syntax)** and a few **additional features**.
 
 ## Front Matter
 
-Markdown documents can have associated metadata at the top called [Front Matter](https://jekyllrb.com/docs/front-matter/):
+Markdown documents have metadata at the very top called [Front Matter](https://jekyllrb.com/docs/front-matter/):
 
 ```md
 ---
@@ -16,12 +16,14 @@ description: My document description
 sidebar_label: My doc
 ---
 
-Markdown content
+## Markdown heading
+
+Markdown text with [links](./hello.md)
 ```
 
-## Markdown links
+## Links
 
-Regular Markdown links are supported using url paths or relative file paths.
+Regular Markdown links are supported, using url paths or relative file paths.
 
 ```md
 Let's see how to [Create a page](/create-a-page).
@@ -31,13 +33,13 @@ Let's see how to [Create a page](/create-a-page).
 Let's see how to [Create a page](./create-a-page.md).
 ```
 
-Let's see how to [Create a page](./create-a-page.md).
+**Result:** Let's see how to [Create a page](./create-a-page.md).
 
-## Markdown images
+## Images
 
 Regular Markdown images are supported.
 
-Add an image at `static/img/docusaurus.png` and use this Markdown declaration:
+Add an image at `static/img/docusaurus.png` and display it in Markdown:
 
 ```md
 ![Docusaurus logo](/img/docusaurus.png)
@@ -91,38 +93,48 @@ This action is dangerous
 
 :::
 
-## React components
+## MDX and React Components
 
-Thanks to [MDX](https://mdxjs.com/), you can make your doc more interactive and use React components inside Markdown:
+[MDX](https://mdxjs.com/) can make your documentation more **interactive** and allows using any **React components inside Markdown**:
 
 ```jsx
 export const Highlight = ({children, color}) => (
   <span
     style={{
       backgroundColor: color,
-      borderRadius: '2px',
-      color: 'red',
-      padding: '0.2rem',
+      borderRadius: '20px',
+      color: '#fff',
+      padding: '10px',
+      cursor: 'pointer',
+    }}
+    onClick={() => {
+      alert(`You clicked the color ${color} with label ${children}`)
     }}>
     {children}
   </span>
 );
 
-<Highlight color="#25c2a0">Docusaurus green</Highlight> and <Highlight color="#1877F2">Facebook blue</Highlight> are my favorite colors.
+This is <Highlight color="#25c2a0">Docusaurus green</Highlight> !
+
+This is <Highlight color="#1877F2">Facebook blue</Highlight> !
 ```
 
 export const Highlight = ({children, color}) => (
   <span
     style={{
       backgroundColor: color,
-      borderRadius: '2px',
+      borderRadius: '20px',
       color: '#fff',
-      padding: '0.2rem',
+      padding: '10px',
+      cursor: 'pointer',
+    }}
+    onClick={() => {
+      alert(`You clicked the color ${color} with label ${children}`);
     }}>
     {children}
   </span>
 );
 
-<Highlight color="#25c2a0">Docusaurus green</Highlight> and <Highlight color="#1877F2">
-  Facebook blue
-</Highlight> are my favorite colors.
+This is <Highlight color="#25c2a0">Docusaurus green</Highlight> !
+
+This is <Highlight color="#1877F2">Facebook blue</Highlight> !

packages/docusaurus-init/templates/classic/docs/thank-you.md

@@ -1,17 +0,0 @@
----
-title: Thank you!
----
-
-Congratulations on making it this far!
-
-You have learned the **basics of Docusaurus** and made some changes to the **initial template**.
-
-But Docusaurus has **much more to offer**!
-
-## What's next?
-
-- [Read the official documentation](https://v2.docusaurus.io/).
-- [Design and Layout your Docusaurus site](https://v2.docusaurus.io/docs/styling-layout)
-- [Integrate a search bar into your site](https://v2.docusaurus.io/docs/search)
-- [Find inspirations in Docusaurus showcase](https://v2.docusaurus.io/showcase)
-- [Get involved in the Docusaurus Community](https://v2.docusaurus.io/community/support)

packages/docusaurus-init/templates/classic/docs/translate-your-site.md

@@ -0,0 +1,86 @@
+---
+title: Translate your site
+---
+
+Let's translate `docs/getting-started.md` to French.
+
+## Configure i18n
+
+Modify `docusaurus.config.js` to add support for the `fr` locale:
+
+```js title="docusaurus.config.js"
+module.exports = {
+  i18n: {
+    defaultLocale: 'en',
+    locales: ['en', 'fr'],
+  },
+};
+```
+
+## Translate a doc
+
+Copy the `docs/getting-started.md` file to the `i18n/fr` directory:
+
+```bash
+mkdir -p i18n/fr/docusaurus-plugin-content-docs/current/
+
+cp docs/getting-started.md i18n/fr/docusaurus-plugin-content-docs/current/getting-started.md
+```
+
+Translate `i18n/fr/docusaurus-plugin-content-docs/current/getting-started.md` in French.
+
+## Start your localized site
+
+Start your site on the French locale:
+
+```bash
+npm run start -- --locale fr
+```
+
+Your localized site is accessible at `http://localhost:3000/fr/` and the `Getting Started` page is translated.
+
+:::warning
+
+In development, you can only use one locale at a same time.
+
+:::
+
+## Add a Locale Dropdown
+
+To navigate seamlessly across languages, add a locale dropdown.
+
+Modify the `docusaurus.config.js` file:
+
+```js title="docusaurus.config.js"
+module.exports = {
+  themeConfig: {
+    navbar: {
+      items: [
+        // highlight-start
+        {
+          type: 'localeDropdown',
+        },
+        // highlight-end
+      ],
+    },
+  },
+};
+```
+
+The locale dropdown now appears in your navbar:
+
+![Locale Dropdown](/img/tutorial/localeDropdown.png)
+
+## Build your localized site
+
+Build your site for a specific locale:
+
+```bash
+npm run build -- --locale fr
+```
+
+Or build your site to include all the locales at once:
+
+```bash
+npm run build
+```

packages/docusaurus-init/templates/classic/docusaurus.config.js

@@ -1,7 +1,7 @@
 /** @type {import('@docusaurus/types').DocusaurusConfig} */
 module.exports = {
   title: 'My Site',
-  tagline: 'The tagline of my site',
+  tagline: 'Dinosaurs are cool',
   url: 'https://your-docusaurus-test-site.com',
   baseUrl: '/',
   onBrokenLinks: 'throw',
@@ -18,12 +18,12 @@ module.exports = {
       },
       items: [
         {
-          to: 'docs/',
-          activeBasePath: 'docs',
-          label: 'Docs',
+          type: 'doc',
+          docId: 'getting-started',
           position: 'left',
+          label: 'Tutorial',
         },
-        {to: 'blog', label: 'Blog', position: 'left'},
+        {to: '/blog', label: 'Blog', position: 'left'},
         {
           href: 'https://github.com/facebook/docusaurus',
           label: 'GitHub',
@@ -39,7 +39,7 @@ module.exports = {
           items: [
             {
               label: 'Getting Started',
-              to: 'docs/',
+              to: '/docs/',
             },
           ],
         },
@@ -65,7 +65,7 @@ module.exports = {
           items: [
             {
               label: 'Blog',
-              to: 'blog',
+              to: '/blog',
             },
             {
               label: 'GitHub',

packages/docusaurus-init/templates/classic/sidebars.js

@@ -1,16 +1,22 @@
 module.exports = {
-  docs: [
+  tutorial: [
     {
       type: 'category',
-      label: 'Docusaurus Tutorial',
+      label: 'Tutorial - Basics',
       items: [
         'getting-started',
         'create-a-page',
         'create-a-document',
         'create-a-blog-post',
         'markdown-features',
-        'thank-you',
+        'deploy-your-site',
+        'congratulations',
       ],
     },
+    {
+      type: 'category',
+      label: 'Tutorial - Extras',
+      items: ['manage-docs-versions', 'translate-your-site'],
+    },
   ],
 };

packages/docusaurus-init/templates/classic/src/components/HomepageFeatures.js

@@ -0,0 +1,62 @@
+import React from 'react';
+import clsx from 'clsx';
+import styles from './HomepageFeatures.module.css';
+
+const FeatureList = [
+  {
+    title: 'Easy to Use',
+    Svg: require('../../static/img/undraw_docusaurus_mountain.svg').default,
+    description: (
+      <>
+        Docusaurus was designed from the ground up to be easily installed and
+        used to get your website up and running quickly.
+      </>
+    ),
+  },
+  {
+    title: 'Focus on What Matters',
+    Svg: require('../../static/img/undraw_docusaurus_tree.svg').default,
+    description: (
+      <>
+        Docusaurus lets you focus on your docs, and we&apos;ll do the chores. Go
+        ahead and move your docs into the <code>docs</code> directory.
+      </>
+    ),
+  },
+  {
+    title: 'Powered by React',
+    Svg: require('../../static/img/undraw_docusaurus_react.svg').default,
+    description: (
+      <>
+        Extend or customize your website layout by reusing React. Docusaurus can
+        be extended while reusing the same header and footer.
+      </>
+    ),
+  },
+];
+
+function Feature({Svg, title, description}) {
+  return (
+    <div className={clsx('col col--4')}>
+      <div className="text--center">
+        <Svg className={styles.featureSvg} alt={title} />
+      </div>
+      <h3>{title}</h3>
+      <p>{description}</p>
+    </div>
+  );
+}
+
+export default function HomepageFeatures() {
+  return (
+    <section className={styles.features}>
+      <div className="container">
+        <div className="row">
+          {FeatureList.map((props, idx) => (
+            <Feature key={idx} {...props} />
+          ))}
+        </div>
+      </div>
+    </section>
+  );
+}

packages/docusaurus-init/templates/classic/src/components/HomepageFeatures.module.css

@@ -0,0 +1,13 @@
+/* stylelint-disable docusaurus/copyright-header */
+
+.features {
+  display: flex;
+  align-items: center;
+  padding: 2rem 0;
+  width: 100%;
+}
+
+.featureSvg {
+  height: 200px;
+  width: 200px;
+}

packages/docusaurus-init/templates/classic/src/pages/index.js

@@ -3,92 +3,35 @@ import clsx from 'clsx';
 import Layout from '@theme/Layout';
 import Link from '@docusaurus/Link';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
-import useBaseUrl from '@docusaurus/useBaseUrl';
-import styles from './styles.module.css';
+import styles from './index.module.css';
+import HomepageFeatures from '../components/HomepageFeatures';
 
-const features = [
-  {
-    title: 'Easy to Use',
-    imageUrl: 'img/undraw_docusaurus_mountain.svg',
-    description: (
-      <>
-        Docusaurus was designed from the ground up to be easily installed and
-        used to get your website up and running quickly.
-      </>
-    ),
-  },
-  {
-    title: 'Focus on What Matters',
-    imageUrl: 'img/undraw_docusaurus_tree.svg',
-    description: (
-      <>
-        Docusaurus lets you focus on your docs, and we&apos;ll do the chores. Go
-        ahead and move your docs into the <code>docs</code> directory.
-      </>
-    ),
-  },
-  {
-    title: 'Powered by React',
-    imageUrl: 'img/undraw_docusaurus_react.svg',
-    description: (
-      <>
-        Extend or customize your website layout by reusing React. Docusaurus can
-        be extended while reusing the same header and footer.
-      </>
-    ),
-  },
-];
-
-function Feature({imageUrl, title, description}) {
-  const imgUrl = useBaseUrl(imageUrl);
+function HomepageHeader() {
+  const {siteConfig} = useDocusaurusContext();
   return (
-    <div className={clsx('col col--4', styles.feature)}>
-      {imgUrl && (
-        <div className="text--center">
-          <img className={styles.featureImage} src={imgUrl} alt={title} />
+    <header className={clsx('hero hero--primary', styles.heroBanner)}>
+      <div className="container">
+        <h1 className="hero__title">{siteConfig.title}</h1>
+        <p className="hero__subtitle">{siteConfig.tagline}</p>
+        <div className={styles.buttons}>
+          <Link className="button button--secondary button--lg" to="/docs">
+            Get Started - Docusaurus Tutorial
+          </Link>
         </div>
-      )}
-      <h3>{title}</h3>
-      <p>{description}</p>
-    </div>
+      </div>
+    </header>
   );
 }
 
 export default function Home() {
-  const context = useDocusaurusContext();
-  const {siteConfig = {}} = context;
+  const {siteConfig} = useDocusaurusContext();
   return (
     <Layout
       title={`Hello from ${siteConfig.title}`}
       description="Description will go into a meta tag in <head />">
-      <header className={clsx('hero hero--primary', styles.heroBanner)}>
-        <div className="container">
-          <h1 className="hero__title">{siteConfig.title}</h1>
-          <p className="hero__subtitle">{siteConfig.tagline}</p>
-          <div className={styles.buttons}>
-            <Link
-              className={clsx(
-                'button button--outline button--secondary button--lg',
-                styles.getStarted,
-              )}
-              to={useBaseUrl('docs/')}>
-              Get Started
-            </Link>
-          </div>
-        </div>
-      </header>
+      <HomepageHeader />
       <main>
-        {features && features.length > 0 && (
-          <section className={styles.features}>
-            <div className="container">
-              <div className="row">
-                {features.map((props, idx) => (
-                  <Feature key={idx} {...props} />
-                ))}
-              </div>
-            </div>
-          </section>
-        )}
+        <HomepageFeatures />
       </main>
     </Layout>
   );

packages/docusaurus-init/templates/classic/src/pages/index.module.css

@@ -23,15 +23,3 @@
   align-items: center;
   justify-content: center;
 }
-
-.features {
-  display: flex;
-  align-items: center;
-  padding: 2rem 0;
-  width: 100%;
-}
-
-.featureImage {
-  height: 200px;
-  width: 200px;
-}

packages/docusaurus-init/tsconfig.json

@@ -4,6 +4,6 @@
     "incremental": true,
     "tsBuildInfoFile": "./lib/.tsbuildinfo",
     "rootDir": "src",
-    "outDir": "lib",
+    "outDir": "lib"
   }
 }