diff --git a/.prettierignore b/.prettierignore
index f1381c97b0d1..24918d15cdbd 100644
--- a/.prettierignore
+++ b/.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__
diff --git a/packages/docusaurus-init/templates/classic/docs/congratulations.md b/packages/docusaurus-init/templates/classic/docs/congratulations.md
new file mode 100644
index 000000000000..32204b9c5510
--- /dev/null
+++ b/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)
diff --git a/packages/docusaurus-init/templates/classic/docs/create-a-blog-post.md b/packages/docusaurus-init/templates/classic/docs/create-a-blog-post.md
index 4485a8af102e..e3bc28503d9c 100644
--- a/packages/docusaurus-init/templates/classic/docs/create-a-blog-post.md
+++ b/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!
diff --git a/packages/docusaurus-init/templates/classic/docs/create-a-document.md b/packages/docusaurus-init/templates/classic/docs/create-a-document.md
index 792212931268..fbcc2782a928 100644
--- a/packages/docusaurus-init/templates/classic/docs/create-a-document.md
+++ b/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
diff --git a/packages/docusaurus-init/templates/classic/docs/create-a-page.md b/packages/docusaurus-init/templates/classic/docs/create-a-page.md
index 1056090453a7..548d5523b069 100644
--- a/packages/docusaurus-init/templates/classic/docs/create-a-page.md
+++ b/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`
diff --git a/packages/docusaurus-init/templates/classic/docs/deploy-your-site.md b/packages/docusaurus-init/templates/classic/docs/deploy-your-site.md
new file mode 100644
index 000000000000..d2583b8c5d76
--- /dev/null
+++ b/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)**).
diff --git a/packages/docusaurus-init/templates/classic/docs/getting-started.md b/packages/docusaurus-init/templates/classic/docs/getting-started.md
index 43df86aac86d..34a553c9072b 100644
--- a/packages/docusaurus-init/templates/classic/docs/getting-started.md
+++ b/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.
-
-## That's it!
+Your site starts at `http://localhost:3000`.
-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.
diff --git a/packages/docusaurus-init/templates/classic/docs/manage-docs-versions.md b/packages/docusaurus-init/templates/classic/docs/manage-docs-versions.md
new file mode 100644
index 000000000000..1f2cd1a8b39f
--- /dev/null
+++ b/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:
+
+
+
+## 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`
diff --git a/packages/docusaurus-init/templates/classic/docs/markdown-features.mdx b/packages/docusaurus-init/templates/classic/docs/markdown-features.mdx
index 622391df57f6..9b9f9ca0767d 100644
--- a/packages/docusaurus-init/templates/classic/docs/markdown-features.mdx
+++ b/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
@@ -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}) => (
{
+ alert(`You clicked the color ${color} with label ${children}`)
}}>
{children}
);
-Docusaurus green and Facebook blue are my favorite colors.
+This is Docusaurus green !
+
+This is Facebook blue !
```
export const Highlight = ({children, color}) => (
{
+ alert(`You clicked the color ${color} with label ${children}`);
}}>
{children}
);
-Docusaurus green and
- Facebook blue
- are my favorite colors.
+This is Docusaurus green !
+
+This is Facebook blue !
diff --git a/packages/docusaurus-init/templates/classic/docs/thank-you.md b/packages/docusaurus-init/templates/classic/docs/thank-you.md
deleted file mode 100644
index 808847e61fe3..000000000000
--- a/packages/docusaurus-init/templates/classic/docs/thank-you.md
+++ /dev/null
@@ -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)
diff --git a/packages/docusaurus-init/templates/classic/docs/translate-your-site.md b/packages/docusaurus-init/templates/classic/docs/translate-your-site.md
new file mode 100644
index 000000000000..4c2eaf0c9602
--- /dev/null
+++ b/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:
+
+
+
+## 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
+```
diff --git a/packages/docusaurus-init/templates/classic/docusaurus.config.js b/packages/docusaurus-init/templates/classic/docusaurus.config.js
index 50817231dfbb..023a5534a8ed 100644
--- a/packages/docusaurus-init/templates/classic/docusaurus.config.js
+++ b/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',
diff --git a/packages/docusaurus-init/templates/classic/sidebars.js b/packages/docusaurus-init/templates/classic/sidebars.js
index df5cb8f79fb5..5ed8bc649a5f 100644
--- a/packages/docusaurus-init/templates/classic/sidebars.js
+++ b/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'],
+ },
],
};
diff --git a/packages/docusaurus-init/templates/classic/src/components/HomepageFeatures.js b/packages/docusaurus-init/templates/classic/src/components/HomepageFeatures.js
new file mode 100644
index 000000000000..19c618e64b62
--- /dev/null
+++ b/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'll do the chores. Go
+ ahead and move your docs into the docs 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 (
+
+