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
77 changes: 77 additions & 0 deletions packages/docusaurus-init/templates/classic/docs/create-a-doc.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,77 @@
---
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
├── ...
```

At the top of the file, specify the `id` and `title` of your document. The purpose is so that Docusaurus can identify your document when generating your site. After that you can start adding your document's content.
stevenhansel marked this conversation as resolved.
Show resolved Hide resolved

```mdx
---
id: hello
title: Hello, World!
---

## Hello, World!

This is your first document in **Docusaurus**, Congratulations!
```

:::note

By default, id of the document is the `filename` of the document. So, you can omit it if your filename already resembles the id.
stevenhansel marked this conversation as resolved.
Show resolved Hide resolved

:::



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

You can add `hello.md` to the sidebar by adding it to `sidebars.js`
stevenhansel marked this conversation as resolved.
Show resolved Hide resolved

Open `sidebars.js` and add the `id` of `hello.md` which is `hello` to the items in docs sidebar.
stevenhansel marked this conversation as resolved.
Show resolved Hide resolved

```js
module.exports = {
docs: [
{
type: 'category',
label: 'Docusaurus Tutorial',
items: ['getting-started', 'markdown-features', 'create-a-doc', 'hello'],
stevenhansel marked this conversation as resolved.
Show resolved Hide resolved
},
],
};
```

Check your sidebar now, and you can access `hello.md` from the docs sidebar now!


## Making your document as the home page
stevenhansel marked this conversation as resolved.
Show resolved Hide resolved

If you want to make `hello.md` as your docs home page, then you can add `slug` to the header fields.

```mdx
---
id: hello
title: Hello, World!
slug: /
---

Hello, World!
```
50 changes: 50 additions & 0 deletions packages/docusaurus-init/templates/classic/docs/create-a-page.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
---
title: Create a Page
---

This page will help you to create standalone pages in Docusaurus, either with React or Markdown.

## Creating a React Page

Create a file: `/src/pages/react.js`
stevenhansel marked this conversation as resolved.
Show resolved Hide resolved

```jsx title="/src/pages/react.js"
import React from "react";

function HelloWorld() {
return (
stevenhansel marked this conversation as resolved.
Show resolved Hide resolved
<div>
<h1>Hello, World!</h1>
</div>
)
}
```

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.

## Creating a Markdown Page

Create a file: `/src/pages/markdown.md`

```mdx title="/src/pages/markdown.md"
---
title: Hello, World!
description: This is a page created with Markdown
hide_table_of_contents: true
stevenhansel marked this conversation as resolved.
Show resolved Hide resolved
---

# Hello, World!

```

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` -> `<baseUrl>`
stevenhansel marked this conversation as resolved.
Show resolved Hide resolved
- `/src/pages/foo.js` -> `<baseUrl>/foo`
- `/src/pages/foo/bar.js` -> `<baseUrl>/foo/bar`
31 changes: 31 additions & 0 deletions packages/docusaurus-init/templates/classic/docs/create-a-post.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
---
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!

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.

Loading