tree: 12b2e49226c4e2709e024011996a8475c81b424c [path history] [tgz]
  1. docs/
  2. website/
  3. .editorconfig
  4. .eslintignore
  5. .eslintrc
  6. .gitattributes
  7. .gitignore
  8. .prettierignore
  9. .prettierrc
  10. package.json
  11. README.md
  12. yarn.lock
docs-site/README.md

Apache SINGA Website

Local Set Up

This website is created with Docusaurus. To set up the website locally,

  1. Install yarn

  2. Install node (version>=10).

  3. Install dependencies

# in singa-doc/docs-site folder
$ yarn install
  1. Run a development server with hot-reloading which updates the webpages immediately upon the modifications to the source files,
# in singa-doc/docs-site folder
$ yarn run start:website

Generate Static HTML Files for Deployment

To create a static build of your website, run the following script from the website directory:

$ yarn run build # or npm run build

The generated html files are under website/build/singa-doc/.

Update and Add Pages

Navigation Bar

To add links to docs, custom pages or external website to the top navigation bar, edit the headerLinks field of website/siteConfig.js:

{
  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' },
    ...
  ],
  ...
}

For more information about the navigation bar, click here

Documentation

All the technical documents are located in the singa-doc/doc-site/docs folder. They are considered as the documentation for next version. The URLs for these webpages are like docs/next/xxx.html.

Versioned documents are in website/versioned_docs/version-${version}, where ${version} is the version number.
The URLs for the webpages of a specific version are docs/version-${version}/xxx.html. For the latest version, you can also visit the webpages using docs/xxx.html (without specifying the version). Suppose the current latest version is v2.0 and we are going to release v3.0. By running

yarn run version 3.0.0

The documents for the current next version will be copied into website/versioned_docs/version-3.0.0.

To add a new document for the next version,

  1. Create the doc as a new markdown file in /docs, example docs/newly-created-doc.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:
// Add newly-created-doc to the Getting Started category of docs
{
  "docs": {
    "Getting Started": [
      "quick-start",
      "newly-created-doc" // new doc here
    ],
    ...
  },
  ...
}

If the sidebar does not exist, you need to add it in the sidebar.json file.

Static assets are under docs/assets. For more information about adding new docs, click here

News

News posts are added as blog posts. To add a news post, create a new file with the format YYYY-MM-DD-My-Blog-Post-Title.md in singa-doc/doc-site/website/blog, e.g., website/blog/2018-05-21-New-Blog-Post.md

---
author: Frank Li
authorURL: https://twitter.com/foobarbaz
authorFBID: 503283835
title: New Blog Post
---

Lorem Ipsum...

There is a link from the top navigation bar to the blog view due to the following setting in website/siteConfig.js:

headerLinks: [
    ...
    { blog: true, label: 'Blog' },
    ...
]

Static assets are under website/blog/assets. For more information about blog posts, click here.

Customized Pages

Docusaurus uses React components to build pages. The components are saved as .js files in website/pages/en: 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:

{
  headerLinks: [
    ...
    { page: 'my-new-custom-page', label: 'My New Custom Page' },
    ...
  ],
  ...
}

For more information about custom pages, click here.