13 changed files with 1 additions and 497 deletions
@ -1,8 +0,0 @@
|
||||
{ |
||||
"label": "Tutorial - Basics", |
||||
"position": 16, |
||||
"link": { |
||||
"type": "generated-index", |
||||
"description": "5 minutes to learn the most important Docusaurus concepts." |
||||
} |
||||
} |
||||
@ -1,23 +0,0 @@
|
||||
--- |
||||
sidebar_position: 6 |
||||
--- |
||||
|
||||
# Congratulations! |
||||
|
||||
You have just 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](../tutorial-extras/manage-docs-versions.md)** and **[i18n](../tutorial-extras/translate-your-site.md)**. |
||||
|
||||
Anything **unclear** or **buggy** in this tutorial? [Please report it!](https://github.com/facebook/docusaurus/discussions/4610) |
||||
|
||||
## What's next? |
||||
|
||||
- Read the [official documentation](https://docusaurus.io/) |
||||
- Modify your site configuration with [`docusaurus.config.js`](https://docusaurus.io/docs/api/docusaurus-config) |
||||
- Add navbar and footer items with [`themeConfig`](https://docusaurus.io/docs/api/themes/configuration) |
||||
- Add a custom [Design and Layout](https://docusaurus.io/docs/styling-layout) |
||||
- Add a [search bar](https://docusaurus.io/docs/search) |
||||
- Find inspirations in the [Docusaurus showcase](https://docusaurus.io/showcase) |
||||
- Get involved in the [Docusaurus Community](https://docusaurus.io/community/support) |
||||
@ -1,34 +0,0 @@
|
||||
--- |
||||
sidebar_position: 3 |
||||
--- |
||||
|
||||
# Create a Blog Post |
||||
|
||||
Docusaurus creates a **page for each blog post**, but also a **blog index page**, a **tag system**, an **RSS** feed... |
||||
|
||||
## Create your first Post |
||||
|
||||
Create a file at `blog/2021-02-28-greetings.md`: |
||||
|
||||
```md title="blog/2021-02-28-greetings.md" |
||||
--- |
||||
slug: greetings |
||||
title: Greetings! |
||||
authors: |
||||
- name: Joel Marcey |
||||
title: Co-creator of Docusaurus 1 |
||||
url: https://github.com/JoelMarcey |
||||
image_url: https://github.com/JoelMarcey.png |
||||
- name: Sébastien Lorber |
||||
title: Docusaurus maintainer |
||||
url: https://sebastienlorber.com |
||||
image_url: https://github.com/slorber.png |
||||
tags: [greetings] |
||||
--- |
||||
|
||||
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](http://localhost:3000/blog/greetings). |
||||
@ -1,57 +0,0 @@
|
||||
--- |
||||
sidebar_position: 2 |
||||
--- |
||||
|
||||
# Create a Document |
||||
|
||||
Documents are **groups of pages** connected through: |
||||
|
||||
- a **sidebar** |
||||
- **previous/next navigation** |
||||
- **versioning** |
||||
|
||||
## Create your first Doc |
||||
|
||||
Create a Markdown file at `docs/hello.md`: |
||||
|
||||
```md title="docs/hello.md" |
||||
# Hello |
||||
|
||||
This is my **first Docusaurus document**! |
||||
``` |
||||
|
||||
A new document is now available at [http://localhost:3000/docs/hello](http://localhost:3000/docs/hello). |
||||
|
||||
## Configure the Sidebar |
||||
|
||||
Docusaurus automatically **creates a sidebar** from the `docs` folder. |
||||
|
||||
Add metadata to customize the sidebar label and position: |
||||
|
||||
```md title="docs/hello.md" {1-4} |
||||
--- |
||||
sidebar_label: 'Hi!' |
||||
sidebar_position: 3 |
||||
--- |
||||
|
||||
# Hello |
||||
|
||||
This is my **first Docusaurus document**! |
||||
``` |
||||
|
||||
It is also possible to create your sidebar explicitly in `sidebars.js`: |
||||
|
||||
```js title="sidebars.js" |
||||
module.exports = { |
||||
tutorialSidebar: [ |
||||
'intro', |
||||
// highlight-next-line |
||||
'hello', |
||||
{ |
||||
type: 'category', |
||||
label: 'Tutorial', |
||||
items: ['tutorial-basics/create-a-document'], |
||||
}, |
||||
], |
||||
}; |
||||
``` |
||||
@ -1,43 +0,0 @@
|
||||
--- |
||||
sidebar_position: 1 |
||||
--- |
||||
|
||||
# Create a Page |
||||
|
||||
Add **Markdown or React** files to `src/pages` to create a **standalone page**: |
||||
|
||||
- `src/pages/index.js` → `localhost:3000/` |
||||
- `src/pages/foo.md` → `localhost:3000/foo` |
||||
- `src/pages/foo/bar.js` → `localhost:3000/foo/bar` |
||||
|
||||
## Create your first React Page |
||||
|
||||
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'; |
||||
|
||||
export default function MyReactPage() { |
||||
return ( |
||||
<Layout> |
||||
<h1>My React page</h1> |
||||
<p>This is a React page</p> |
||||
</Layout> |
||||
); |
||||
} |
||||
``` |
||||
|
||||
A new page is now available at [http://localhost:3000/my-react-page](http://localhost:3000/my-react-page). |
||||
|
||||
## Create your first Markdown Page |
||||
|
||||
Create a file at `src/pages/my-markdown-page.md`: |
||||
|
||||
```mdx title="src/pages/my-markdown-page.md" |
||||
# My Markdown page |
||||
|
||||
This is a Markdown page |
||||
``` |
||||
|
||||
A new page is now available at [http://localhost:3000/my-markdown-page](http://localhost:3000/my-markdown-page). |
||||
@ -1,31 +0,0 @@
|
||||
--- |
||||
sidebar_position: 5 |
||||
--- |
||||
|
||||
# Deploy your site |
||||
|
||||
Docusaurus is a **static-site-generator** (also called **[Jamstack](https://jamstack.org/)**). |
||||
|
||||
It builds your site as simple **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` folder. |
||||
|
||||
## Deploy your site |
||||
|
||||
Test your production build locally: |
||||
|
||||
```bash |
||||
npm run serve |
||||
``` |
||||
|
||||
The `build` folder is now served at [http://localhost:3000/](http://localhost:3000/). |
||||
|
||||
You can now deploy the `build` folder **almost anywhere** easily, **for free** or very small cost (read the **[Deployment Guide](https://docusaurus.io/docs/deployment)**). |
||||
@ -1,150 +0,0 @@
|
||||
--- |
||||
sidebar_position: 4 |
||||
--- |
||||
|
||||
# Markdown Features |
||||
|
||||
Docusaurus supports **[Markdown](https://daringfireball.net/projects/markdown/syntax)** and a few **additional features**. |
||||
|
||||
## Front Matter |
||||
|
||||
Markdown documents have metadata at the top called [Front Matter](https://jekyllrb.com/docs/front-matter/): |
||||
|
||||
```text title="my-doc.md" |
||||
// highlight-start |
||||
--- |
||||
id: my-doc-id |
||||
title: My document title |
||||
description: My document description |
||||
slug: /my-custom-url |
||||
--- |
||||
// highlight-end |
||||
|
||||
## Markdown heading |
||||
|
||||
Markdown text with [links](./hello.md) |
||||
``` |
||||
|
||||
## 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). |
||||
``` |
||||
|
||||
**Result:** Let's see how to [Create a page](./create-a-page.md). |
||||
|
||||
## Images |
||||
|
||||
Regular Markdown images are supported. |
||||
|
||||
You can use absolute paths to reference images in the static directory (`static/img/docusaurus.png`): |
||||
|
||||
```md |
||||
 |
||||
``` |
||||
|
||||
 |
||||
|
||||
You can reference images relative to the current file as well. This is particularly useful to colocate images close to the Markdown files using them: |
||||
|
||||
```md |
||||
 |
||||
``` |
||||
|
||||
## Code Blocks |
||||
|
||||
Markdown code blocks are supported with Syntax highlighting. |
||||
|
||||
```jsx title="src/components/HelloDocusaurus.js" |
||||
function HelloDocusaurus() { |
||||
return ( |
||||
<h1>Hello, Docusaurus!</h1> |
||||
) |
||||
} |
||||
``` |
||||
|
||||
```jsx title="src/components/HelloDocusaurus.js" |
||||
function HelloDocusaurus() { |
||||
return <h1>Hello, Docusaurus!</h1>; |
||||
} |
||||
``` |
||||
|
||||
## 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 |
||||
|
||||
::: |
||||
|
||||
## MDX and React Components |
||||
|
||||
[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: '20px', |
||||
color: '#fff', |
||||
padding: '10px', |
||||
cursor: 'pointer', |
||||
}} |
||||
onClick={() => { |
||||
alert(`You clicked the color ${color} with label ${children}`) |
||||
}}> |
||||
{children} |
||||
</span> |
||||
); |
||||
|
||||
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: '20px', |
||||
color: '#fff', |
||||
padding: '10px', |
||||
cursor: 'pointer', |
||||
}} |
||||
onClick={() => { |
||||
alert(`You clicked the color ${color} with label ${children}`); |
||||
}}> |
||||
{children} |
||||
</span> |
||||
); |
||||
|
||||
This is <Highlight color="#25c2a0">Docusaurus green</Highlight> ! |
||||
|
||||
This is <Highlight color="#1877F2">Facebook blue</Highlight> ! |
||||
@ -1,7 +0,0 @@
|
||||
{ |
||||
"label": "Tutorial - Extras", |
||||
"position": 17, |
||||
"link": { |
||||
"type": "generated-index" |
||||
} |
||||
} |
||||
|
Before Width: | Height: | Size: 25 KiB |
|
Before Width: | Height: | Size: 27 KiB |
@ -1,55 +0,0 @@
|
||||
--- |
||||
sidebar_position: 1 |
||||
--- |
||||
|
||||
# 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` folder 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` |
||||
@ -1,88 +0,0 @@
|
||||
--- |
||||
sidebar_position: 2 |
||||
--- |
||||
|
||||
# Translate your site |
||||
|
||||
Let's translate `docs/intro.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/intro.md` file to the `i18n/fr` folder: |
||||
|
||||
```bash |
||||
mkdir -p i18n/fr/docusaurus-plugin-content-docs/current/ |
||||
|
||||
cp docs/intro.md i18n/fr/docusaurus-plugin-content-docs/current/intro.md |
||||
``` |
||||
|
||||
Translate `i18n/fr/docusaurus-plugin-content-docs/current/intro.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/](http://localhost:3000/fr/) and the `Getting Started` page is translated. |
||||
|
||||
:::caution |
||||
|
||||
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 |
||||
``` |
||||
Loading…
Reference in new issue