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 new file mode 100644 index 000000000000..4485a8af102e --- /dev/null +++ b/packages/docusaurus-init/templates/classic/docs/create-a-blog-post.md @@ -0,0 +1,25 @@ +--- +title: Create a Blog Post +--- + +This page will help you on how to create blog posts in Docusaurus. + +## Create a Blog Post + +Create a file at `blog/2021-02-28-greetings.md`: + +```md title="blog/2021-02-28-greetings.md" +--- +title: Greetings! +author: Steven Hansel +author_title: Docusaurus Contributor +author_url: https://github.com/ShinteiMai +author_image_url: https://github.com/ShinteiMai.png +--- + +Congratulations, you have made your first post! + +Feel free to play around and edit this post as much you like. +``` + +A new blog post is now available at `http://localhost:3000/blog/greetings`. diff --git a/packages/docusaurus-init/templates/classic/docs/create-a-doc.md b/packages/docusaurus-init/templates/classic/docs/create-a-doc.md deleted file mode 100644 index 26a26f0078d2..000000000000 --- a/packages/docusaurus-init/templates/classic/docs/create-a-doc.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -title: Create a Document ---- - -This page will help you to create your first document with Docusaurus. - -## Creating a simple document - -Create a markdown file `docs/hello.md`. - -```md -website # root directory of your site -├── docs -│ └── hello.md -├── src -│ └── pages -├── docusaurus.config.js -├── ... -``` - -Copy the example below to the file that you've just created: - -```mdx ---- -id: hello -title: Hello, World! ---- - -## Hello, World! - -This is your first document in **Docusaurus**, Congratulations! -``` - -:::note - -By default, the id of the document is the `filename` of the document. So, you can omit it if your filename already resembles the id. - -::: - -After creating and saving the file, run your development server and go to `http://localhost:3000/docs/hello` in your browser. - -## Adding your document to the sidebar - -Open `sidebars.js` and add the `id` of `hello.md` (`hello`) to the items in the docs sidebar. - -```diff -module.exports = { - docs: [ - { - type: 'category', - label: 'Docusaurus Tutorial', -- items: ['getting-started', 'markdown-features', 'create-a-doc'], -+ items: ['getting-started', 'markdown-features', 'create-a-doc', 'hello'], - }, - ], -}; -``` diff --git a/packages/docusaurus-init/templates/classic/docs/create-a-document.md b/packages/docusaurus-init/templates/classic/docs/create-a-document.md new file mode 100644 index 000000000000..792212931268 --- /dev/null +++ b/packages/docusaurus-init/templates/classic/docs/create-a-document.md @@ -0,0 +1,38 @@ +--- +title: Create a Document +--- + +Documents are pages with a **sidebar**, a **previous/next navigation** and many other useful features. + +## Create a Document + +Create a markdown file at `docs/my-doc.md`: + +```mdx title="docs/hello.md" +--- +title: Hello, World! +--- + +## Hello, World! + +This is your first document in **Docusaurus**, Congratulations! +``` + +A new document is now available at `http://localhost:3000/docs/hello`. + +## Add your document to the sidebar + +Add `hello` to the `sidebars.js` file: + +```diff title="sidebars.js" +module.exports = { + docs: [ + { + type: 'category', + label: 'Docusaurus Tutorial', +- items: ['getting-started', 'create-a-doc', ...], ++ items: ['getting-started', 'create-a-doc', 'hello', ...], + }, + ], +}; +``` 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 1527d86d1e12..1056090453a7 100644 --- a/packages/docusaurus-init/templates/classic/docs/create-a-page.md +++ b/packages/docusaurus-init/templates/classic/docs/create-a-page.md @@ -2,51 +2,44 @@ title: Create a Page --- -This page will help you to create standalone pages in Docusaurus, either with React or Markdown. +Any React or Markdown file created under `src/pages` directory is converted into a website page: -## Creating a React Page +- `src/pages/index.js` -> `localhost:3000/` +- `src/pages/foo.md` -> `localhost:3000/foo` +- `src/pages/foo/bar.js` -> `localhost:3000/foo/bar` -Create a file: `./src/pages/react.js` +## Create a React Page -```jsx title="/src/pages/react.js" -import React from "react"; +Create a file at `src/pages/my-react-page.js`: + +```jsx title="src/pages/my-react-page.js" +import React from 'react'; import Layout from '@theme/Layout'; function HelloWorld() { - return ( - -
-

Hello, World!

-
-
- ) + return ( + +

My React page

+

This is a React page

+
+ ); } ``` -Save the file, and the development server will automatically reload the changes. Open `http://localhost:3000/react`, to see the page that you just created with React. +A new page is now available at `http://localhost:3000/my-react-page`. -## Creating a Markdown Page +## Create a Markdown Page -Create a file: `/src/pages/markdown.md` +Create a file at `src/pages/my-markdown-page.md`: -```mdx title="/src/pages/markdown.md" +```mdx title="src/pages/my-markdown-page.md" --- -title: Hello, World! -description: This is a page created with Markdown +title: My Markdown page --- -# Hello, World! +# My Markdown page +This is a Markdown page ``` -Save the file, and the development server will automatically reload the changes. Open `http://localhost:3000/markdown`, to see the page that you just created with Markdown. - -## Routing - -Any JavaScript (React) or Markdown files that you create under `/src/pages` directory will be automatically converted into a website page. - -Here are some examples: - -- `/src/pages/index.js` -> `localhost:3000/` -- `/src/pages/foo.js` -> `localhost:3000/foo` -- `/src/pages/foo/bar.js` -> `localhost:3000/foo/bar` +A new page is now available at `http://localhost:3000/my-markdown-page`. diff --git a/packages/docusaurus-init/templates/classic/docs/create-a-post.md b/packages/docusaurus-init/templates/classic/docs/create-a-post.md deleted file mode 100644 index a8123b59cac8..000000000000 --- a/packages/docusaurus-init/templates/classic/docs/create-a-post.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: Create a Post ---- - -This page will help you on how to create blog posts in Docusaurus. - -## Adding Posts - -In order to add a post in the blog, create a file: `/blog/2021-02-28-greetings`. - -The format for filename of a post is `YYYY-MM-DD-post-title.md`, you have to follow this format because the post date is extracted from the file name. - -```md ---- -slug: greetings -title: Greetings! -author: Steven Hansel -author_title: Docusaurus Contributor -author_url: https://github.com/ShinteiMai -author_image_url: https://avatars.githubusercontent.com/u/54180475?s=460&u=dea92f5adfe1adb82d983200553508851c3a96a0&v=4 -tags: [greetings, docusaurus] ---- - -Congratulations, you have made your first post! - -Feel free to play around and edit this post as much you like. - -``` - -The post should be generated automatically after you save the file. Open `http://localhost:3000/blog/greetings`, and you should see your created post! - diff --git a/packages/docusaurus-init/templates/classic/docs/getting-started.md b/packages/docusaurus-init/templates/classic/docs/getting-started.md index 6e46e996c68d..43df86aac86d 100644 --- a/packages/docusaurus-init/templates/classic/docs/getting-started.md +++ b/packages/docusaurus-init/templates/classic/docs/getting-started.md @@ -1,30 +1,28 @@ --- -title: Getting Started +title: Getting Started slug: / --- -## Setting up the development environment - -### Step 1: Generate a Docusaurus site +## Step 1: Generate a new Docusaurus site If you haven't already, generate a new Docusaurus site using the classic template: ```shell -npx @docusaurus/init@latest init my-documentation classic +npx @docusaurus/init@latest init my-website classic ``` -### Step 2: Start your Docusaurus site +## Step 2: Start your Docusaurus site -Run the development server: +Run the development server in the newly created `my-website` folder: ```shell +cd my-website + npx docusaurus start ``` -Open `docs/getting-started.md` and edit some lines. The site should reload automatically and display your changes. +Open `docs/getting-started.md` and edit some lines. The site reloads automatically and display your changes. -### That's it! +## That's it! Congratulations! You've successfully run and modified your Docusaurus project. - - diff --git a/packages/docusaurus-init/templates/classic/docs/interactiveDoc.mdx b/packages/docusaurus-init/templates/classic/docs/interactiveDoc.mdx deleted file mode 100644 index f0eb5f0d47f4..000000000000 --- a/packages/docusaurus-init/templates/classic/docs/interactiveDoc.mdx +++ /dev/null @@ -1,27 +0,0 @@ ---- -id: mdx -title: Powered by MDX ---- - -You can write JSX and use React components within your Markdown thanks to [MDX](https://mdxjs.com/). - -The `.mdx` extension is not required, but will enable better support from tooling (IDE, Prettier...). - -export const Highlight = ({children, color}) => ( - alert('Highlight pressed!')}> - {children} - -); - -Docusaurus green and - Facebook blue - are my favorite colors. - -I can write **Markdown** alongside my _JSX_! diff --git a/packages/docusaurus-init/templates/classic/docs/markdown-features.mdx b/packages/docusaurus-init/templates/classic/docs/markdown-features.mdx index 5a185ffefe12..622391df57f6 100644 --- a/packages/docusaurus-init/templates/classic/docs/markdown-features.mdx +++ b/packages/docusaurus-init/templates/classic/docs/markdown-features.mdx @@ -2,32 +2,98 @@ title: Markdown Features --- -In this page, we will see some of the tools that will help you to build your documentation site with Docusaurus. +Docusaurus supports the [Markdown](https://daringfireball.net/projects/markdown/syntax) syntax and has some additional features. -## Frontmatters +## Front Matter + +Markdown documents can have associated metadata at the top called [Front Matter](https://jekyllrb.com/docs/front-matter/): ```md --- -id: slash -title: Slash, Our Mascot! -hide_title: false -hide_table_of_contents: false -sidebar_label: Say Hello to Slash! -description: We named our mascot Slash because most documentations start with // -keywords: - - docs - - docusaurus - - mascot +id: my-doc +title: My document title +description: My document description +sidebar_label: My doc --- + +Markdown content +``` + +## Markdown links + +Regular Markdown links are supported using url paths or relative file paths. + +```md +Let's see how to [Create a page](/create-a-page). +``` + +```md +Let's see how to [Create a page](./create-a-page.md). ``` -## Referencing other documents +Let's see how to [Create a page](./create-a-page.md). + +## Markdown images + +Regular Markdown images are supported. + +Add an image at `static/img/docusaurus.png` and use this Markdown declaration: ```md -I am referencing [this](/create-a-page.md) tutorial. +![Docusaurus logo](/img/docusaurus.png) +``` + +![Docusaurus logo](/img/docusaurus.png) + +## Code Blocks + +Markdown code blocks are supported with Syntax highlighting. + + ```jsx title="src/components/HelloDocusaurus.js" + function HelloDocusaurus() { + return ( +

Hello, Docusaurus!

+ ) + } + ``` + +```jsx title="src/components/HelloDocusaurus.js" +function HelloDocusaurus() { + return

Hello, Docusaurus!

; +} ``` -## Embedding React components with MDX +## Admonitions + +Docusaurus has a special syntax to create admonitions and callouts: + + :::tip My tip + + Use this awesome feature option + + ::: + + :::danger Take care + + This action is dangerous + + ::: + +:::tip My tip + +Use this awesome feature option + +::: + +:::danger Take care + +This action is dangerous + +::: + +## React components + +Thanks to [MDX](https://mdxjs.com/), you can make your doc more interactive and use React components inside Markdown: ```jsx export const Highlight = ({children, color}) => ( @@ -35,7 +101,7 @@ export const Highlight = ({children, color}) => ( style={{ backgroundColor: color, borderRadius: '2px', - color: '#fff', + color: 'red', padding: '0.2rem', }}> {children} @@ -60,19 +126,3 @@ export const Highlight = ({children, color}) => ( Docusaurus green and Facebook blue are my favorite colors. - -## Code Blocks - - ```jsx title="src/components/HelloDocusaurus.js" - function HelloDocusaurus() { - return ( -

Hello, Docusaurus!

- ) - } - ``` - -```jsx title="src/components/HelloDocusaurus.js" -function HelloDocusaurus() { - return

Hello, Docusaurus!

; -} -``` diff --git a/packages/docusaurus-init/templates/classic/docs/thank-you.md b/packages/docusaurus-init/templates/classic/docs/thank-you.md index c3089df9ec15..808847e61fe3 100644 --- a/packages/docusaurus-init/templates/classic/docs/thank-you.md +++ b/packages/docusaurus-init/templates/classic/docs/thank-you.md @@ -2,11 +2,16 @@ title: Thank you! --- -Congratulations on making it this far! You have learned the basics of Docusaurus and made some changes to the initial template. If you want to continue to learn about Docusaurus, you can refer to the list below. +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). +- [Get involved in the Docusaurus Community](https://v2.docusaurus.io/community/support) diff --git a/packages/docusaurus-init/templates/classic/sidebars.js b/packages/docusaurus-init/templates/classic/sidebars.js index e563c352cd51..df5cb8f79fb5 100644 --- a/packages/docusaurus-init/templates/classic/sidebars.js +++ b/packages/docusaurus-init/templates/classic/sidebars.js @@ -5,9 +5,9 @@ module.exports = { label: 'Docusaurus Tutorial', items: [ 'getting-started', - 'create-a-doc', 'create-a-page', - 'create-a-post', + 'create-a-document', + 'create-a-blog-post', 'markdown-features', 'thank-you', ], diff --git a/packages/docusaurus-init/templates/classic/static/img/docusaurus.png b/packages/docusaurus-init/templates/classic/static/img/docusaurus.png new file mode 100644 index 000000000000..f458149e3c8f Binary files /dev/null and b/packages/docusaurus-init/templates/classic/static/img/docusaurus.png differ