mirror of
https://github.com/facebook/docusaurus.git
synced 2025-08-04 01:09:20 +02:00
Yangshun Tay
GitHub
parent
152fe614b4
commit
35e6648169
13 changed files with 715 additions and 2 deletions
|
|
@ -0,0 +1,120 @@
|
|||
---
|
||||
id: version-1.9.0-installation
|
||||
title: Installation
|
||||
original_id: installation
|
||||
---
|
||||
|
||||
Docusaurus was designed from the ground up to be easily installed and used to get your website up and running quickly.
|
||||
|
||||
## Installing Docusaurus
|
||||
|
||||
We have created an easy script that will get all of the infrastructure set up for you:
|
||||
|
||||
1. Ensure you have the latest version of [Node](https://nodejs.org/en/download/) installed. We also recommend you install [Yarn](https://yarnpkg.com/en/docs/install) as well.
|
||||
|
||||
> You have to be on Node >= 8.x and Yarn >= 1.5.
|
||||
|
||||
1. Create a project, if none exists, and change your directory to this project's root.
|
||||
|
||||
You will be creating the docs in this directory. The root directory may
|
||||
contain other files. The Docusaurus installation script will create two new
|
||||
directories: `docs` and `website`.
|
||||
|
||||
> Commonly, either an existing or newly created GitHub project will be the location for your Docusaurus site, but that is not mandatory to use Docusaurus.
|
||||
|
||||
1. Run the Docusaurus installation script: `npx docusaurus-init`.
|
||||
|
||||
> If you don't have Node 8.2+ or if you prefer to install Docusaurus globally, run `yarn global add docusaurus-init` or `npm install --global docusaurus-init`. After that, run `docusaurus-init`.
|
||||
|
||||
## Verifying Installation
|
||||
|
||||
Along with previously existing files and directories, your root directory will now contain a structure similar to:
|
||||
|
||||
```bash
|
||||
root-directory
|
||||
├── Dockerfile
|
||||
├── README.md
|
||||
├── docker-compose.yml
|
||||
├── docs
|
||||
│ ├── doc1.md
|
||||
│ ├── doc2.md
|
||||
│ ├── doc3.md
|
||||
│ ├── exampledoc4.md
|
||||
│ └── exampledoc5.md
|
||||
└── website
|
||||
├── blog
|
||||
│ ├── 2016-03-11-blog-post.md
|
||||
│ ├── 2017-04-10-blog-post-two.md
|
||||
│ ├── 2017-09-25-testing-rss.md
|
||||
│ ├── 2017-09-26-adding-rss.md
|
||||
│ └── 2017-10-24-new-version-1.0.0.md
|
||||
├── core
|
||||
│ └── Footer.js
|
||||
├── package.json
|
||||
├── pages
|
||||
├── sidebars.json
|
||||
├── siteConfig.js
|
||||
└── static
|
||||
```
|
||||
|
||||
## Running the example website
|
||||
|
||||
After running the Docusaurus initialization script, `docusaurus-init` as
|
||||
described in the [Installation](#installing-docusaurus) section, you will have a
|
||||
runnable, example website to use as your site's base. To run:
|
||||
|
||||
1. `cd website`
|
||||
1. From within the `website` directory, run the local webserver using
|
||||
`yarn start` or `npm start`.
|
||||
1. Load the example site at http://localhost:3000 if it did not already open
|
||||
automatically. If port 3000 has already been taken, another port will be used. Look at the console messages to see which.
|
||||
|
||||
You should see the example site loaded in your web browser. There's also a LiveReload server running and any changes made to the docs and files in the `website` directory will cause the page to refresh. A randomly generated primary and secondary theme color will be picked for you.
|
||||
|
||||
|
||||
|
||||
### Launching the server behind a proxy
|
||||
|
||||
If you are behind a corporate proxy, you need to disable it for the development server requests. It can be done using the `NO_PROXY` environment variable.
|
||||
|
||||
```sh
|
||||
SET NO_PROXY=localhost
|
||||
yarn start (or npm run start)
|
||||
```
|
||||
|
||||
## Updating Your Docusaurus Version
|
||||
|
||||
At any time after Docusaurus is installed, you can check your current version of Docusaurus by going into the `website` directory and typing `yarn outdated docusaurus` or `npm outdated docusaurus`.
|
||||
|
||||
You will see something like this:
|
||||
|
||||
```
|
||||
$ yarn outdated
|
||||
Using globally installed version of Yarn
|
||||
yarn outdated v1.5.1
|
||||
warning package.json: No license field
|
||||
warning No license field
|
||||
info Color legend :
|
||||
"<red>" : Major Update backward-incompatible updates
|
||||
"<yellow>" : Minor Update backward-compatible features
|
||||
"<green>" : Patch Update backward-compatible bug fixes
|
||||
Package Current Wanted Latest Package Type URL
|
||||
docusaurus 1.0.9 1.2.0 1.2.0 devDependencies https://github.com/facebook/Docusaurus#readme
|
||||
✨ Done in 0.41s.
|
||||
```
|
||||
|
||||
> If there is no noticeable version output from the `outdated` commands, then you are up-to-date.
|
||||
|
||||
You can update to the [latest version](https://www.npmjs.com/package/docusaurus) of Docusaurus by:
|
||||
|
||||
```
|
||||
yarn upgrade docusaurus --latest
|
||||
```
|
||||
|
||||
or
|
||||
|
||||
```
|
||||
npm update docusaurus
|
||||
```
|
||||
|
||||
> If you are finding that you are getting errors after your upgrade, try to either clear your Babel cache (usually it's in a [temporary directory](https://babeljs.io/docs/en/babel-register/#environment-variables) or run the Docusaurus server (e.g., `yarn start`) with the `BABEL_DISABLE_CACHE=1` environment configuration.
|
||||
|
|
@ -0,0 +1,58 @@
|
|||
---
|
||||
id: version-1.9.0-site-preparation
|
||||
title: Site Preparation
|
||||
original_id: site-preparation
|
||||
---
|
||||
|
||||
After [installing Docusaurus](getting-started-installation.md), you now have a skeleton to work from for your specific website. The following discusses the rest of the Docusaurus structure in order for you to prepare your site.
|
||||
|
||||
## Directory Structure
|
||||
|
||||
As shown after you [installed Docusaurus](getting-started-installation.md), the initialization script created a directory structure similar to:
|
||||
|
||||
```bash
|
||||
root-directory
|
||||
├── docs
|
||||
│ ├── doc1.md
|
||||
│ ├── doc2.md
|
||||
│ ├── doc3.md
|
||||
│ ├── exampledoc4.md
|
||||
│ └── exampledoc5.md
|
||||
└── website
|
||||
├── blog
|
||||
│ ├── 2016-03-11-blog-post.md
|
||||
│ ├── 2017-04-10-blog-post-two.md
|
||||
│ ├── 2017-09-25-testing-rss.md
|
||||
│ ├── 2017-09-26-adding-rss.md
|
||||
│ └── 2017-10-24-new-version-1.0.0.md
|
||||
├── core
|
||||
│ └── Footer.js
|
||||
├── package.json
|
||||
├── pages
|
||||
├── sidebars.json
|
||||
├── siteConfig.js
|
||||
└── static
|
||||
```
|
||||
|
||||
### Directory Descriptions
|
||||
|
||||
* **Documentation Source Files**: The `docs` directory
|
||||
contains example documentation files written in Markdown.
|
||||
* **Blog**: The `website/blog` directory contains examples of blog posts written in markdown.
|
||||
* **Pages**: The `website/pages` directory contains example top-level pages for the site.
|
||||
* **Static files and images**: The `website/static` directory contains static assets used by the example site.
|
||||
|
||||
### Key Files
|
||||
|
||||
* **Footer**: The `website/core/Footer.js` file is a React component that acts
|
||||
as the footer for the site generated by Docusaurus and should be customized by the user.
|
||||
* **Configuration file**: The `website/siteConfig.js` file is the main
|
||||
configuration file used by Docusaurus.
|
||||
* **Sidebars**: The `sidebars.json` file contains the structure and ordering
|
||||
of the documentation files.
|
||||
|
||||
## Preparation Notes
|
||||
|
||||
You will need to keep the `website/siteConfig.js` and `website/core/Footer.js` files, but may edit them as you wish. The value of the `customDocsPath` key in `website/siteConfig.js` can be modified if you wish to use a different directory name or path. The `website` directory can also be renamed to anything you want it to be.
|
||||
|
||||
However, you should keep the `website/pages` and `website/static` directories. You may change the content inside them as you wish. At the bare minimum you should have an `en/index.js` or `en/index.html` file inside `website/pages` and an image to use as your header icon inside `website/static`.
|
||||
138
website-1.x/versioned_docs/version-1.9.0/guides-blog.md
Normal file
138
website-1.x/versioned_docs/version-1.9.0/guides-blog.md
Normal file
|
|
@ -0,0 +1,138 @@
|
|||
---
|
||||
id: version-1.9.0-adding-blog
|
||||
title: Adding a Blog
|
||||
original_id: adding-blog
|
||||
---
|
||||
|
||||
## Initial Setup
|
||||
|
||||
To setup your site's blog, start by creating a `blog` directory within your repo's `website` directory.
|
||||
|
||||
Then, add a header link to your blog within `siteConfig.js`:
|
||||
|
||||
```js
|
||||
headerLinks: [
|
||||
...
|
||||
{ blog: true, label: 'Blog' },
|
||||
...
|
||||
]
|
||||
```
|
||||
|
||||
## Adding Posts
|
||||
|
||||
To publish in the blog, create a file within the blog directory with a formatted name of `YYYY-MM-DD-My-Blog-Post-Title.md`. The post date is extracted from the file name.
|
||||
|
||||
For example, at `website/blog/2017-08-18-Introducing-Docusaurus.md`:
|
||||
|
||||
```yml
|
||||
---
|
||||
author: Frank Li
|
||||
authorURL: https://twitter.com/foobarbaz
|
||||
authorFBID: 503283835
|
||||
title: Introducing Docusaurus
|
||||
---
|
||||
|
||||
Lorem Ipsum...
|
||||
```
|
||||
|
||||
## Header Options
|
||||
|
||||
The only required field is `title`; however, we provide options to add author information to your blog post as well.
|
||||
|
||||
* `author` - The text label of the author byline.
|
||||
* `authorURL` - The URL associated with the author. This could be a Twitter, GitHub, Facebook account, etc.
|
||||
* `authorFBID` - The Facebook profile ID that is used to fetch the profile picture.
|
||||
* `authorImageURL` - The URL to the author's image. (Note: If you use both `authorFBID` and `authorImageURL`, `authorFBID` will take precedence. Don't include `authorFBID` if you want `authorImageURL` to appear.)
|
||||
* `title` - The blog post title.
|
||||
|
||||
## Summary Truncation
|
||||
|
||||
Use the `<!--truncate-->` marker in your blog post to represent what will be shown as the summary when viewing all published blog posts. Anything above `<!--truncate-->` will be part of the summary. For example:
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: Truncation Example
|
||||
---
|
||||
|
||||
All this will be part of the blog post summary.
|
||||
|
||||
Even this.
|
||||
|
||||
<!--truncate-->
|
||||
|
||||
But anything from here on down will not be.
|
||||
|
||||
Not this.
|
||||
|
||||
Or this.
|
||||
```
|
||||
|
||||
## Changing How Many Blog Posts Show on Sidebar
|
||||
|
||||
By default, 5 recent blog posts are shown on the sidebar.
|
||||
|
||||
You can configure a specific amount of blog posts to show by adding a `blogSidebarCount` setting to your `siteConfig.js`.
|
||||
|
||||
The available options are an integer representing the number of posts you wish to show or a string with the value `'ALL'`.
|
||||
|
||||
Example:
|
||||
|
||||
```js
|
||||
blogSidebarCount: 'ALL',
|
||||
```
|
||||
|
||||
## Changing The Sidebar Title
|
||||
|
||||
You can configure a specific sidebar title by adding a `blogSidebarTitle` setting to your `siteConfig.js`.
|
||||
|
||||
The option is an object which can have the keys `default` and `all`. Specifying a value for `default` allows you to change the default sidebar title. Specifying a value for `all` allows you to change the sidebar title when the `blogSidebarCount` option is set to `'ALL'`.
|
||||
|
||||
Example:
|
||||
|
||||
```js
|
||||
blogSidebarTitle: { default: 'Recent posts', all: 'All blog posts' },
|
||||
```
|
||||
|
||||
## RSS Feed
|
||||
|
||||
Docusaurus provides a simple RSS feed for your blog posts. Both RSS and Atom feed formats are supported. This data is automatically to your website page's HTML `<HEAD>` tag.
|
||||
|
||||
A summary of the post's text is provided in the RSS feed up to the `<!--truncate-->`. If no `<!--truncate-->` tag is found, then all text up 250 characters are used.
|
||||
|
||||
## Social Buttons
|
||||
|
||||
If you want Facebook and/or Twitter social buttons at the bottom of your blog posts, set the `facebookAppId` and/or `twitter` [site configuration](api-site-config.md) options in `siteConfig.js`.
|
||||
|
||||
## Advanced Topics
|
||||
|
||||
### I want to run in "Blog Only" mode.
|
||||
|
||||
You can run your Docusaurus site without a landing page and instead have your blog load first.
|
||||
|
||||
To do this:
|
||||
|
||||
1. Create a file `index.html` in `website/static/`.
|
||||
1. Place the contents of the template below into `website/static/index.html`
|
||||
1. Customize the `<title>` of `website/static/index.html`
|
||||
1. Delete the dynamic landing page `website/pages/en/index.js`
|
||||
|
||||
> Now, when Docusaurus generates or builds your site, it will copy the file from `static/index.html` and place it in the site's main directory. The static file is served when a visitor arrives on your page. When the page loads it will redirect the visitor to `/blog`.
|
||||
|
||||
You can use this template:
|
||||
|
||||
```html
|
||||
<!DOCTYPE HTML>
|
||||
<html lang="en-US">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<meta http-equiv="refresh" content="0; url=blog/">
|
||||
<script type="text/javascript">
|
||||
window.location.href = 'blog/';
|
||||
</script>
|
||||
<title>Title of Your Blog</title>
|
||||
</head>
|
||||
<body>
|
||||
If you are not redirected automatically, follow this <a href="blog/">link</a>.
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
|
@ -0,0 +1,67 @@
|
|||
---
|
||||
id: version-1.9.0-tutorial-create-new-site
|
||||
title: Create a New Site
|
||||
original_id: tutorial-create-new-site
|
||||
---
|
||||
|
||||
In this section we'll get our Docusaurus site up and running for local development. The process takes less than a few minutes.
|
||||
|
||||
<img alt="Docusaurus browser" src="/img/undraw_docusaurus_browser.svg" class="docImage"/>
|
||||
|
||||
## Scaffold the Site
|
||||
|
||||
1. Execute the `docusaurus-init` command in your terminal.
|
||||
|
||||
```sh
|
||||
docusaurus-init
|
||||
```
|
||||
|
||||
The following contents will be created for you in the directory you are in.
|
||||
|
||||
```sh
|
||||
├── Dockerfile
|
||||
├── docker-compose.yml
|
||||
├── docs
|
||||
│ ├── doc1.md
|
||||
│ ├── doc2.md
|
||||
│ ├── doc3.md
|
||||
│ ├── exampledoc4.md
|
||||
│ └── exampledoc5.md
|
||||
└── website
|
||||
├── README.md
|
||||
├── blog
|
||||
│ ├── 2016-03-11-blog-post.md
|
||||
│ ├── 2017-04-10-blog-post-two.md
|
||||
│ ├── 2017-09-25-testing-rss.md
|
||||
│ ├── 2017-09-26-adding-rss.md
|
||||
│ └── 2017-10-24-new-version-1.0.0.md
|
||||
├── core
|
||||
│ └── Footer.js
|
||||
├── package.json
|
||||
├── pages
|
||||
│ └── en
|
||||
│ ├── help.js
|
||||
│ ├── index.js
|
||||
│ └── users.js
|
||||
├── sidebars.json
|
||||
├── siteConfig.js
|
||||
├── static
|
||||
│ ├── css
|
||||
│ │ └── custom.css
|
||||
│ └── img
|
||||
│ ├── docusaurus.svg
|
||||
│ ├── favicon
|
||||
│ │ └── favicon.ico
|
||||
│ ├── favicon.png
|
||||
│ └── oss_logo.png
|
||||
└── yarn.lock
|
||||
```
|
||||
|
||||
There would be some example documentation and blog pages generated.
|
||||
|
||||
2. Run `cd website` to go into the `website` directory.
|
||||
1. Run `npm start` or `yarn start`.
|
||||
|
||||
A browser window will open up at http://localhost:3000.
|
||||
|
||||
Congratulations, you have just made your first Docusaurus site! Click around the pages generated for you to see what's available.
|
||||
|
|
@ -0,0 +1,90 @@
|
|||
---
|
||||
id: version-1.9.0-tutorial-create-pages
|
||||
title: Create Pages
|
||||
original_id: tutorial-create-pages
|
||||
---
|
||||
|
||||
In this section we will learn about creating two new types of pages in Docusaurus, a regular page and a documentation page.
|
||||
|
||||
<img alt="Docusaurus MacBook" src="/img/undraw_docusaurus_tree.svg" class="docImage"/>
|
||||
|
||||
## Creating a Regular Page
|
||||
|
||||
1. Go into the `pages/en` directory and create a file called `hello-world.js` with the following contents:
|
||||
|
||||
```
|
||||
const React = require('react');
|
||||
|
||||
const CompLibrary = require('../../core/CompLibrary.js');
|
||||
|
||||
const Container = CompLibrary.Container;
|
||||
const GridBlock = CompLibrary.GridBlock;
|
||||
|
||||
function HelloWorld(props) {
|
||||
return (
|
||||
<div className="docMainWrapper wrapper">
|
||||
<Container className="mainContainer documentContainer postContainer">
|
||||
<h1>Hello World!</h1>
|
||||
<p>This is my first page!</p>
|
||||
</Container>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
|
||||
module.exports = HelloWorld;
|
||||
```
|
||||
|
||||
2. Go to http://localhost:3000/hello-world and you should be able to see the new page.
|
||||
1. Change the text within the `<p>...</p>` to "I'm at F8!". The browser should refresh automatically to reflect the changes.
|
||||
|
||||
```diff
|
||||
- <p>This is my first page!</p>
|
||||
+ <p>I'm at F8!</p>
|
||||
```
|
||||
|
||||
React is being used as a templating engine for rendering static markup. You can leverage on the expressability of React to build rich web content. Learn more about creating pages [here](custom-pages).
|
||||
|
||||
<img alt="Docusaurus React" src="/img/undraw_docusaurus_react.svg" class="docImage"/>
|
||||
|
||||
## Create a Documentation Page
|
||||
|
||||
1. Create a new file in the `docs` folder called `f8.md`.
|
||||
1. Paste the following contents:
|
||||
|
||||
```
|
||||
---
|
||||
id: f8
|
||||
title: Hello F8
|
||||
---
|
||||
|
||||
Hello F8! I'm at the Docusaurus classroom session!
|
||||
|
||||
## Using Docusaurus to Create Open Source Websites
|
||||
|
||||
In this session, we learned how Docusaurus makes it really simple to create a website for open source project documentation and get hands on by creating a Docusaurus website.
|
||||
```
|
||||
|
||||
3. Go to `sidebars.json` and add `"f8"` after `"doc1"`. This ID should be the same one as in the Markdown file above.
|
||||
|
||||
```diff
|
||||
{
|
||||
"docs": {
|
||||
"Docusaurus": [
|
||||
"doc1",
|
||||
+ "f8"
|
||||
],
|
||||
"First Category": ["doc2"],
|
||||
"Second Category": ["doc3"]
|
||||
},
|
||||
"docs-other": {
|
||||
"First Category": ["doc4", "doc5"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
4. Kill your webserver (<kbd>Cmd</kbd> + <kbd>C</kbd> or <kbd>Ctrl</kbd> + <kbd>C</kbd>) and restart it (with `npm run start`) because a server restart is needed for sidebar changes.
|
||||
5. Navigate to http://localhost:3000/docs/f8.
|
||||
|
||||
You've created your first documentation page on Docusaurus! The `sidebars.json` is where you specify the order of your documentation pages and in the front matter of the Markdown file is where you provide metadata about that page.
|
||||
|
||||
Learn more about creating docs pages [here](navigation).
|
||||
|
|
@ -0,0 +1,39 @@
|
|||
---
|
||||
id: version-1.9.0-tutorial-publish-site
|
||||
title: Publish the Site
|
||||
original_id: tutorial-publish-site
|
||||
---
|
||||
|
||||
<img alt="Docusaurus Facebook" src="/img/undraw_docusaurus_fb.svg" class="docImage"/>
|
||||
|
||||
Next we'll learn how to publish the site to the WWW for everyone to browse! For the purpose of the tutorial, we'll use GitHub pages to host our website. But you can use any static file hosting service that you want, e.g. Netlify, Amazon S3, etc.
|
||||
|
||||
## Put the Site Online
|
||||
|
||||
Kill the webserver first by pressing Cmd + C or Ctrl + C depending on your operating system.
|
||||
|
||||
In `website/siteConfig.js`, fill in the following fields:
|
||||
|
||||
```
|
||||
const siteConfig = {
|
||||
...
|
||||
url: 'https://USERNAME.github.io', // Replace USERNAME with your GitHub username.
|
||||
baseUrl: '/docusaurus-tutorial/', // The name of your GitHub project.
|
||||
projectName: 'docusaurus-tutorial', // The name of your GitHub project. Same as above.
|
||||
organizationName: 'USERNAME' // Your GitHub username.
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
2. In the `website` directory, run `npm run build` or `yarn build`. This will generate a `build` directory inside the `website` directory containing the `.html` files from all of your docs and other pages included in `pages`. Make sure the `build` directory is there before running the next step.
|
||||
3. Replace `<GIT_USER>` with your GitHub username and run the following command.
|
||||
|
||||
```
|
||||
$ GIT_USER=<GIT_USER> CURRENT_BRANCH=master USE_SSH=true npm run publish-gh-pages
|
||||
```
|
||||
|
||||
The built code will be pushed to the `gh-pages` branch of your repository.
|
||||
|
||||
4. Go to `https://USERNAME.github.io/docusaurus-tutorial/` and view your site in action!
|
||||
|
||||
> Note that when you run `npm run start` again, the `baseUrl` will now be part of the path.
|
||||
78
website-1.x/versioned_docs/version-1.9.0/tutorial-setup.md
Normal file
78
website-1.x/versioned_docs/version-1.9.0/tutorial-setup.md
Normal file
|
|
@ -0,0 +1,78 @@
|
|||
---
|
||||
id: version-1.9.0-tutorial-setup
|
||||
title: Setting Up
|
||||
original_id: tutorial-setup
|
||||
---
|
||||
|
||||
This tutorial is geared at first-time users who want detailed instructions on how to go from zero to a Docusaurus website that has versions. Let's start!
|
||||
|
||||
<img alt="Docusaurus campfire" src="/img/undraw_docusaurus_mountain.svg" class="docImage"/>
|
||||
|
||||
## Install Node.js
|
||||
|
||||
Node.js is an environment that can run JavaScript code outside of a web browser and is used to write and run server-side JavaScript apps.
|
||||
|
||||
> Docusaurus' minimum supported Node.js version is Node 8, but more recent versions will work as well.
|
||||
|
||||
1. Open your Terminal.
|
||||
1. If you have `brew` on your OS, run the following command to install Node (a JavaScript runtime that allows you to run JavaScript on the server) and `npm` the package manager (allows you to install npm modules from your terminal).
|
||||
|
||||
```sh
|
||||
brew install node
|
||||
```
|
||||
|
||||
Alternatively, you can download an installer from the [Node.js homepage](https://nodejs.org/en/).
|
||||
|
||||
## Check your Node.js installation
|
||||
|
||||
Check that you have the minimum required version installed by running the following command:
|
||||
|
||||
```sh
|
||||
node -v
|
||||
```
|
||||
|
||||
You should see a version larger than Node 8.
|
||||
|
||||
```sh
|
||||
node -v
|
||||
v8.15.1
|
||||
```
|
||||
|
||||
## Install Yarn (Optional)
|
||||
|
||||
We highly recommend you to install Yarn, an alternative package manager that has superb performance for managing your NPM dependencies. Check it out [here](https://yarnpkg.com/en/docs/install).
|
||||
|
||||
> You can still proceed with the tutorial without Yarn.
|
||||
|
||||
## Create a GitHub Repository
|
||||
|
||||
1. Go to https://github.com/ and sign up for an account if you don't already have one.
|
||||
1. Click on **"New Repository"** or go to https://github.com/new.
|
||||
1. Name your repository without spaces. For e.g. `docusaurus-tutorial`.
|
||||
1. Proceed to create the repository without adding `.gitignore` or a license.
|
||||
|
||||
<img alt="GitHub create repo" src="/img/tutorial-git-clone.png" class="docImage"/>
|
||||
|
||||
5. Clone your repository to your local machine:
|
||||
|
||||
```sh
|
||||
git clone git@github.com:USERNAME/docusaurus-tutorial.git
|
||||
```
|
||||
|
||||
6. `cd` into the repository which you just created.
|
||||
|
||||
## Install the Docusaurus init command
|
||||
|
||||
Docusaurus comes with a command line tool to help you scaffold a Docusaurus site with some example templates. Let's install the installer!
|
||||
|
||||
1. Run the following command:
|
||||
|
||||
```sh
|
||||
npm install --global docusaurus-init
|
||||
```
|
||||
|
||||
or if you have Yarn:
|
||||
|
||||
```sh
|
||||
yarn global add docusaurus-init
|
||||
```
|
||||
58
website-1.x/versioned_docs/version-1.9.0/tutorial-version.md
Normal file
58
website-1.x/versioned_docs/version-1.9.0/tutorial-version.md
Normal file
|
|
@ -0,0 +1,58 @@
|
|||
---
|
||||
id: version-1.9.0-tutorial-version
|
||||
title: Add Versions
|
||||
original_id: tutorial-version
|
||||
---
|
||||
|
||||
With an example site deployed, we can now try out one of the killer features of Docusaurus - versioned documentation. Versioned documentation helps to show relevant documention to the users for the current version of the tool they are using and also hide unreleased documentation from users, reducing confusion. Documentation for older versions are also preserved and accessible to users of older versions of the tool even as the latest documentation changes.
|
||||
|
||||
<img alt="Docusaurus process" src="/img/undraw_docusaurus_process.svg" class="docImage"/>
|
||||
|
||||
## Releasing a Version
|
||||
|
||||
Assuming we are happy with the current state of the documentation and we want to freeze it as the v1.0.0 docs. We first run the following command to generate a `versions.js` file, which will be used to list down all the versions of docs in the project.
|
||||
|
||||
```sh
|
||||
npm run examples versions # yarn examples versions
|
||||
```
|
||||
|
||||
Next, we run a command with the version we want to create, e.g. 1.0.0,
|
||||
|
||||
```sh
|
||||
npm run version 1.0.0 # yarn version 1.0.0
|
||||
```
|
||||
|
||||
This will preserve all documents currently in the `docs` directory and make them available as documentation for version 1.0.0.
|
||||
|
||||
Documents in the `docs` directory will be considered part of version next and they are available, for example, at the URL `localhost:3000/<baseUrl>/docs/next/doc1`. Documents from the latest version use the URL `docs/doc1`.
|
||||
|
||||
Let's test out that versioning actually works. We can go to `docs/doc1.md` and change the first line of the body:
|
||||
|
||||
```diff
|
||||
---
|
||||
id: doc1
|
||||
title: Latin-ish
|
||||
sidebar_label: Example Page
|
||||
---
|
||||
|
||||
- Check the [documentation](https://docusaurus.io) for how to use Docusaurus.
|
||||
+ This is the latest version of the docs.
|
||||
|
||||
## Lorem
|
||||
|
||||
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies.
|
||||
```
|
||||
|
||||
If we go to the `localhost:3000/<baseUrl>/docs/doc1` URL in our browser, realize that it's still showing the previous line. That's because the version we're looking at now is the 1.0.0 version, which has already been frozen in time.
|
||||
|
||||
## Next Version
|
||||
|
||||
The latest versions of the docs have to be accessed by adding `next` to the URL: `localhost:3000/<baseUrl>/docs/next/doc1`. Note that the version beside the title also changes to `next` when we are on that URL.
|
||||
|
||||
A versions page has been created for us at `localhost:3000/<baseUrl>/versions` which shows a list of the current versions of the documentation. See that both `1.0.0` and `master` are being listed here and they correctly link to the respective versions of documentation.
|
||||
|
||||
Go ahead and publish your versioned site!
|
||||
|
||||
## Wrap Up
|
||||
|
||||
That's all folks! In this short tutorial you have experienced how easy it was to create a documentation website from scratch and making versions for them. There are many more things you can do with Docusaurus, such as adding a blog, search and translations. Check out the Guides section for more.
|
||||
Loading…
Add table
Add a link
Reference in a new issue