Skip to content
Snippets Groups Projects
Commit 9f80fc02 authored by Achilleas Pipinellis's avatar Achilleas Pipinellis
Browse files

Update to docusaurus 2

parent c1be7008
No related branches found
No related tags found
No related merge requests found
Showing
with 285 additions and 399 deletions
.DS_Store
node_modules
lib/core/metadata.js
lib/core/MetadataBlog.js
website/translated_docs
website/build/
website/yarn.lock
website/node_modules
website/i18n/*
image: node:9.11.1
image: node:15.12-alpine3.13
pages:
stages:
- test
- deploy
test:
stage: test
script:
- cd website
- yarn install
- yarn build
# The build directory is created based on the value set for projectName in
# website/siteConfig.js. If you change it there, you need to change it here
# as well.
- mv ./build/docusaurus ../public
except:
- master
pages:
stage: deploy
script:
- cd website
- yarn install
- yarn build
- mv ./build ../public
artifacts:
paths:
- public
only:
- master
- master
![Build Status](https://gitlab.com/pages/mkdocs/badges/master/pipeline.svg)
![Build Status](https://gitlab.com/pages/docusaurus/badges/master/pipeline.svg)
---
Example [Docusaurus](https://docusaurus.io/en/) website using GitLab Pages.
Example [Docusaurus](https://docusaurus.io/) website using GitLab Pages.
Learn more about GitLab Pages at https://about.gitlab.com/features/pages and the official
documentation https://docs.gitlab.com/ee/user/project/pages/.
......@@ -15,20 +15,31 @@ This project's static Pages are built by [GitLab CI/CD](https://about.gitlab.com
following the steps defined in [`.gitlab-ci.yml`](.gitlab-ci.yml):
```yaml
image: node:9.11.1
image: node:15.12-alpine3.13
stages:
- test
- deploy
test:
stage: test
script:
- cd website
- yarn install
- yarn build
except:
- master
pages:
stage: deploy
script:
- cd website
- yarn install
- yarn build
# The build directory is created based on the value set for projectName in
# website/siteConfig.js. If you change it there, you need to change it here
# as well.
- mv ./build/docusaurus ../public
- cd website
- yarn install
- yarn build
- mv ./build ../public
artifacts:
paths:
- public
- public
only:
- master
```
......@@ -60,9 +71,7 @@ To work locally with this project, you'll have to follow the steps below:
yarn build
```
The build directory is created based on the value set for `projectName` in
`website/siteConfig.js`. If you didn't change this value, the website will
be built under `website/build/docusaurus/`.
The website will be built under `website/build/`.
Read more at the [Docusaurus documentation](https://docusaurus.io).
......@@ -82,7 +91,7 @@ served on the root path, you will need to:
If you have forked this project, and want to use it under a subpath, you will
need to:
1. Open `website/siteConfig.js` and change:
1. Open `website/docusaurus.config.js` and change:
1. The `url` to be `https://namespace.gitlab.io` or your
[custom domain](https://docs.gitlab.com/ee/user/project/pages/custom_domains_ssl_tls_certification/index.html) of choice.
1. The `baseUrl` to be the same as the name of your project.
......
# Dependencies
/node_modules
# Production
/build
# Generated files
.docusaurus
.cache-loader
# Misc
.DS_Store
.env.local
.env.development.local
.env.test.local
.env.production.local
npm-debug.log*
yarn-debug.log*
yarn-error.log*
image: node:15.12-alpine3.13
stages:
- test
- deploy
test:
stage: test
script:
- cd website
- yarn install
- yarn build
except:
- master
pages:
stage: deploy
script:
- cd website
- yarn install
- yarn build
- mv ./build ../public
artifacts:
paths:
- public
only:
- master
This website was created with [Docusaurus](https://docusaurus.io/).
# Website
# What's In This Document
This website is built using [Docusaurus 2](https://v2.docusaurus.io/), a modern static website generator.
* [Get Started in 5 Minutes](#get-started-in-5-minutes)
* [Directory Structure](#directory-structure)
* [Editing Content](#editing-content)
* [Adding Content](#adding-content)
* [Full Documentation](#full-documentation)
## Installation
## Get Started in 5 Minutes
1. Make sure all the dependencies for the website are installed:
```sh
yarn
```
2. Run your dev server:
```sh
yarn start
```console
yarn install
```
## Directory Structure
## Local Development
Your project file structure should look something like this
```
my-docusaurus/
docs/
doc-1.md
doc-2.md
doc-3.md
website/
blog/
2016-3-11-oldest-post.md
2017-10-24-newest-post.md
core/
node_modules/
pages/
static/
css/
img/
package.json
sidebar.json
siteConfig.js
```console
yarn start
```
# Editing Content
## Editing an existing docs page
Edit docs by navigating to `docs/` and editing the corresponding document:
This command starts a local development server and open up a browser window. Most changes are reflected live without having to restart the server.
`docs/doc-to-be-edited.md`
## Build
```markdown
---
id: page-needs-edit
title: This Doc Needs To Be Edited
---
Edit me...
```console
yarn build
```
More information about [docs](https://docusaurus.io/docs/en/navigation).
## Editing an existing blog post
Edit blog posts by navigating to `website/blog` and editing the corresponding post:
This command generates static content into the `build` directory and can be served using any static contents hosting service.
`website/blog/post-to-be-edited.md`
```markdown
---
id: post-needs-edit
title: This Blog Post Needs To Be Edited
---
## Deployment
Edit me...
```console
GIT_USER=<Your GitHub username> USE_SSH=true yarn deploy
```
More information about [blog posts](https://docusaurus.io/docs/en/adding-blog).
# Adding Content
## Adding a new docs page to an existing sidebar
1. Create the doc as a new markdown file in `/docs`, example `docs/newly-created-doc.md`:
```md
---
id: newly-created-doc
title: This Doc Needs To Be Edited
---
My new content here..
```
1. Refer to that doc's ID in an existing sidebar in `website/sidebar.json`:
```javascript
// Add newly-created-doc to the Getting Started category of docs
{
"docs": {
"Getting Started": [
"quick-start",
"newly-created-doc" // new doc here
],
...
},
...
}
```
More information about [adding new docs](https://docusaurus.io/docs/en/navigation).
## Adding a new blog post
1. Make sure there is a header link to your blog in `website/siteConfig.js`:
```javascript
headerLinks: [
...
{ blog: true, label: 'Blog' },
...
]
```
1. Create the blog post with the format `YYYY-MM-DD-My-Blog-Post-Title.md` in `website/blog`:
`website/blog/2018-05-21-New-Blog-Post.md`
```markdown
---
author: Frank Li
authorURL: https://twitter.com/foobarbaz
authorFBID: 503283835
title: New Blog Post
---
Lorem Ipsum...
```
More information about [blog posts](https://docusaurus.io/docs/en/adding-blog).
## Adding items to your site's top navigation bar
1. Add links to docs, custom pages or external links by editing the headerLinks field of `website/siteConfig.js`:
```javascript
{
headerLinks: [
...
/* you can add docs */
{ doc: 'my-examples', label: 'Examples' },
/* you can add custom pages */
{ page: 'help', label: 'Help' },
/* you can add external links */
{ href: 'https://github.com/facebook/docusaurus', label: 'GitHub' },
...
],
...
}
```
More information about the [navigation bar](https://docusaurus.io/docs/en/navigation).
## Adding custom pages
1. Docusaurus uses React components to build pages. The components are saved as .js files in `website/pages/en`:
1. If you want your page to show up in your navigation header, you will need to update `website/siteConfig.js` to add to the `headerLinks` element:
```javascript
{
headerLinks: [
...
{ page: 'my-new-custom-page', label: 'My New Custom Page' },
...
],
...
}
```
More information about [custom pages](https://docusaurus.io/docs/en/custom-pages).
## Full Documentation
Full documentation can be found on the [website](https://docusaurus.io/).
If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.
module.exports = {
presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
};
---
title: Blog Title
author: Blog Author
authorURL: http://twitter.com/
authorFBID: 100002976521003
---
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus elementum massa eget nulla aliquet sagittis. Proin odio tortor, vulputate ut odio in, ultrices ultricies augue. Cras ornare ultrices lorem malesuada iaculis. Etiam sit amet libero tempor, pulvinar mauris sed, sollicitudin sapien.
<!--truncate-->
Mauris vestibulum ullamcorper nibh, ut semper purus pulvinar ut. Donec volutpat orci sit amet mauris malesuada, non pulvinar augue aliquam. Vestibulum ultricies at urna ut suscipit. Morbi iaculis, erat at imperdiet semper, ipsum nulla sodales erat, eget tincidunt justo dui quis justo. Pellentesque dictum bibendum diam at aliquet. Sed pulvinar, dolor quis finibus ornare, eros odio facilisis erat, eu rhoncus nunc dui sed ex. Nunc gravida dui massa, sed ornare arcu tincidunt sit amet. Maecenas efficitur sapien neque, a laoreet libero feugiat ut.
Nulla facilisi. Maecenas sodales nec purus eget posuere. Sed sapien quam, pretium a risus in, porttitor dapibus erat. Sed sit amet fringilla ipsum, eget iaculis augue. Integer sollicitudin tortor quis ultricies aliquam. Suspendisse fringilla nunc in tellus cursus, at placerat tellus scelerisque. Sed tempus elit a sollicitudin rhoncus. Nulla facilisi. Morbi nec dolor dolor. Orci varius natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Cras et aliquet lectus. Pellentesque sit amet eros nisi. Quisque ac sapien in sapien congue accumsan. Nullam in posuere ante. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia Curae; Proin lacinia leo a nibh fringilla pharetra.
Orci varius natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Proin venenatis lectus dui, vel ultrices ante bibendum hendrerit. Aenean egestas feugiat dui id hendrerit. Orci varius natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Curabitur in tellus laoreet, eleifend nunc id, viverra leo. Proin vulputate non dolor vel vulputate. Curabitur pretium lobortis felis, sit amet finibus lorem suscipit ut. Sed non mollis risus. Duis sagittis, mi in euismod tincidunt, nunc mauris vestibulum urna, at euismod est elit quis erat. Phasellus accumsan vitae neque eu placerat. In elementum arcu nec tellus imperdiet, eget maximus nulla sodales. Curabitur eu sapien eget nisl sodales fermentum.
Phasellus pulvinar ex id commodo imperdiet. Praesent odio nibh, sollicitudin sit amet faucibus id, placerat at metus. Donec vitae eros vitae tortor hendrerit finibus. Interdum et malesuada fames ac ante ipsum primis in faucibus. Quisque vitae purus dolor. Duis suscipit ac nulla et finibus. Phasellus ac sem sed dui dictum gravida. Phasellus eleifend vestibulum facilisis. Integer pharetra nec enim vitae mattis. Duis auctor, lectus quis condimentum bibendum, nunc dolor aliquam massa, id bibendum orci velit quis magna. Ut volutpat nulla nunc, sed interdum magna condimentum non. Sed urna metus, scelerisque vitae consectetur a, feugiat quis magna. Donec dignissim ornare nisl, eget tempor risus malesuada quis.
---
title: New Blog Post
author: Blog Author
authorURL: http://twitter.com/
authorFBID: 100002976521003
---
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus elementum massa eget nulla aliquet sagittis. Proin odio tortor, vulputate ut odio in, ultrices ultricies augue. Cras ornare ultrices lorem malesuada iaculis. Etiam sit amet libero tempor, pulvinar mauris sed, sollicitudin sapien.
<!--truncate-->
Mauris vestibulum ullamcorper nibh, ut semper purus pulvinar ut. Donec volutpat orci sit amet mauris malesuada, non pulvinar augue aliquam. Vestibulum ultricies at urna ut suscipit. Morbi iaculis, erat at imperdiet semper, ipsum nulla sodales erat, eget tincidunt justo dui quis justo. Pellentesque dictum bibendum diam at aliquet. Sed pulvinar, dolor quis finibus ornare, eros odio facilisis erat, eu rhoncus nunc dui sed ex. Nunc gravida dui massa, sed ornare arcu tincidunt sit amet. Maecenas efficitur sapien neque, a laoreet libero feugiat ut.
Nulla facilisi. Maecenas sodales nec purus eget posuere. Sed sapien quam, pretium a risus in, porttitor dapibus erat. Sed sit amet fringilla ipsum, eget iaculis augue. Integer sollicitudin tortor quis ultricies aliquam. Suspendisse fringilla nunc in tellus cursus, at placerat tellus scelerisque. Sed tempus elit a sollicitudin rhoncus. Nulla facilisi. Morbi nec dolor dolor. Orci varius natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Cras et aliquet lectus. Pellentesque sit amet eros nisi. Quisque ac sapien in sapien congue accumsan. Nullam in posuere ante. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia Curae; Proin lacinia leo a nibh fringilla pharetra.
Orci varius natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Proin venenatis lectus dui, vel ultrices ante bibendum hendrerit. Aenean egestas feugiat dui id hendrerit. Orci varius natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Curabitur in tellus laoreet, eleifend nunc id, viverra leo. Proin vulputate non dolor vel vulputate. Curabitur pretium lobortis felis, sit amet finibus lorem suscipit ut. Sed non mollis risus. Duis sagittis, mi in euismod tincidunt, nunc mauris vestibulum urna, at euismod est elit quis erat. Phasellus accumsan vitae neque eu placerat. In elementum arcu nec tellus imperdiet, eget maximus nulla sodales. Curabitur eu sapien eget nisl sodales fermentum.
Phasellus pulvinar ex id commodo imperdiet. Praesent odio nibh, sollicitudin sit amet faucibus id, placerat at metus. Donec vitae eros vitae tortor hendrerit finibus. Interdum et malesuada fames ac ante ipsum primis in faucibus. Quisque vitae purus dolor. Duis suscipit ac nulla et finibus. Phasellus ac sem sed dui dictum gravida. Phasellus eleifend vestibulum facilisis. Integer pharetra nec enim vitae mattis. Duis auctor, lectus quis condimentum bibendum, nunc dolor aliquam massa, id bibendum orci velit quis magna. Ut volutpat nulla nunc, sed interdum magna condimentum non. Sed urna metus, scelerisque vitae consectetur a, feugiat quis magna. Donec dignissim ornare nisl, eget tempor risus malesuada quis.
---
title: Adding RSS Support - RSS Truncation Test
author: Eric Nakagawa
authorURL: http://twitter.com/ericnakagawa
authorFBID: 661277173
---
1234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890
This should be truncated.
<!--truncate-->
This line should never render in XML.
---
title: Adding RSS Support
author: Eric Nakagawa
authorURL: http://twitter.com/ericnakagawa
authorFBID: 661277173
---
This is a test post.
A whole bunch of other information.
---
title: New Version 1.0.0
author: Eric Nakagawa
authorURL: http://twitter.com/ericnakagawa
authorFBID: 661277173
---
This blog post will test file name parsing issues when periods are present.
---
slug: hola
title: Hola
author: Gao Wei
author_title: Docusaurus Core Team
author_url: https://github.com/wgao19
author_image_url: https://avatars1.githubusercontent.com/u/2055384?v=4
tags: [hola, docusaurus]
---
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
---
slug: hello-world
title: Hello
author: Endilie Yacop Sucipto
author_title: Maintainer of Docusaurus
author_url: https://github.com/endiliey
author_image_url: https://avatars1.githubusercontent.com/u/17883920?s=460&v=4
tags: [hello, docusaurus]
---
Welcome to this blog. This blog is created with [**Docusaurus 2 alpha**](https://v2.docusaurus.io/).
<!--truncate-->
This is a test post.
A whole bunch of other information.
---
slug: welcome
title: Welcome
author: Yangshun Tay
author_title: Front End Engineer @ Facebook
author_url: https://github.com/yangshun
author_image_url: https://avatars0.githubusercontent.com/u/1315101?s=400&v=4
tags: [facebook, hello, docusaurus]
---
Blog features are powered by the blog plugin. Simply add files to the `blog` directory. It supports tags as well!
Delete the whole directory if you don't want the blog features. As simple as that!
/**
* Copyright (c) 2017-present, Facebook, Inc.
*
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*/
const React = require('react');
class Footer extends React.Component {
docUrl(doc, language) {
const baseUrl = this.props.config.baseUrl;
const docsUrl = this.props.config.docsUrl;
const docsPart = `${docsUrl ? `${docsUrl}/` : ''}`;
const langPart = `${language ? `${language}/` : ''}`;
return `${baseUrl}${docsPart}${langPart}${doc}`;
}
pageUrl(doc, language) {
const baseUrl = this.props.config.baseUrl;
return baseUrl + (language ? `${language}/` : '') + doc;
}
render() {
return (
<footer className="nav-footer" id="footer">
<section className="sitemap">
<a href={this.props.config.baseUrl} className="nav-home">
{this.props.config.footerIcon && (
<img
src={this.props.config.baseUrl + this.props.config.footerIcon}
alt={this.props.config.title}
width="66"
height="58"
/>
)}
</a>
<div>
<h5>Docs</h5>
<a href={this.docUrl('doc1.html', this.props.language)}>
Getting Started (or other categories)
</a>
<a href={this.docUrl('doc2.html', this.props.language)}>
Guides (or other categories)
</a>
<a href={this.docUrl('doc3.html', this.props.language)}>
API Reference (or other categories)
</a>
</div>
<div>
<h5>Community</h5>
<a href={this.pageUrl('users.html', this.props.language)}>
User Showcase
</a>
<a
href="https://stackoverflow.com/questions/tagged/"
target="_blank"
rel="noreferrer noopener">
Stack Overflow
</a>
<a href="https://discordapp.com/">Project Chat</a>
<a
href="https://twitter.com/"
target="_blank"
rel="noreferrer noopener">
Twitter
</a>
</div>
<div>
<h5>More</h5>
<a href={`${this.props.config.baseUrl}blog`}>Blog</a>
<a href="https://gitlab.com/pages/docusaurus" target="_blank">Built by GitLab Pages</a>
<a href="https://github.com/facebook/docusaurus" target="_blank">Docusaurus on GitHub</a>
<a
className="github-button"
href={this.props.config.repoUrl}
data-icon="octicon-star"
data-count-href="/facebook/docusaurus/stargazers"
data-show-count="true"
data-count-aria-label="# stargazers on GitHub"
aria-label="Star this project on GitHub">
Star
</a>
{this.props.config.twitterUsername && (
<div className="social">
<a
href={`https://twitter.com/${this.props.config.twitterUsername}`}
className="twitter-follow-button">
Follow @{this.props.config.twitterUsername}
</a>
</div>
)}
{this.props.config.facebookAppId && (
<div className="social">
<div
className="fb-like"
data-href={this.props.config.url}
data-colorscheme="dark"
data-layout="standard"
data-share="true"
data-width="225"
data-show-faces="false"
/>
</div>
)}
</div>
</section>
<a
href="https://opensource.facebook.com/"
target="_blank"
rel="noreferrer noopener"
className="fbOpenSource">
<img
src={`${this.props.config.baseUrl}img/oss_logo.png`}
alt="Facebook Open Source"
width="170"
height="45"
/>
</a>
<section className="copyright">{this.props.config.copyright}</section>
</footer>
);
}
}
module.exports = Footer;
---
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`.
---
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', ...],
},
],
};
```
---
title: Create a Page
---
Any React or Markdown file created under `src/pages` directory is converted into a website 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 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';
function HelloWorld() {
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`.
## Create a Markdown Page
Create a file at `src/pages/my-markdown-page.md`:
```mdx title="src/pages/my-markdown-page.md"
---
title: My Markdown page
---
# My Markdown page
This is a Markdown page
```
A new page is now available at `http://localhost:3000/my-markdown-page`.
---
title: Getting Started
slug: /
---
## 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-website classic
```
## Step 2: Start your Docusaurus site
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 reloads automatically and display your changes.
## That's it!
Congratulations! You've successfully run and modified your Docusaurus project.
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment