Skip to main content

Docusaurus

This intranet website is built with Docusaurus framework. The framework relies on Node.js and the content is written in Markdown larnguage. It is very good for documentation and knowledge storage.

Install Nodejs​

On a Mac, you can install Node.js using brew

brew install nodejs

Initialization​

Then you should initialize your webpage from a template. The name I choose is internal_web but you can choose anything you want. classic is the template.

npx create-docusaurus@latest internal_web classic

Start your website​

cd internal_web
npx docusaurus start

Your browser will be directed to httpL/localhost:3000 and you can see your webpage.

Add a page​

Documentation is stored under docs. You can create subfolders under this directory. You also need a _category_.json to generate index for each sub-webpage.

{
  "label": "Orientation",
  "position": 2,
  "link": {
    "type": "generated-index",
    "description": "Welcome to the DENG group! Here are some useful information you would like to start with."
  }
}

Then you can create a markdown file (*.md) for a webpage. You can set some properties for each webpage in the block at the top. More details of the markdown features can be found here.

---
title: Docusaurus
authors: jerry
tags: [technique]
sidebar_position: 2
---

This is the example content ....

Customization​

You can customize your website by editing docusaurus.config.js. Below are some customizations that I used for this website.

const config = {
  themeConfig:
    ({
      // Replace with your project's social card
      image: 'img/docusaurus-social-card.jpg',
      navbar: {
        title: 'Intranet',
        logo: {
          alt: 'My Site Logo',
          src: 'img/logo.svg',
        },
        items: [
          // {
          //   type: 'docSidebar',
          //   sidebarId: 'tutorialSidebar',
          //   position: 'left',
          //   label: 'Home',
          // },
          // {to: 'blog', label: 'Blog', position: 'left'},
          {to: '/category/orientation', label: 'Orientation', position: 'left'},
          {to: '/category/simulation', label: 'Simulation', position: 'left'},
          {to: '/category/research', label: 'Research', position: 'left'},
          {to: '/category/techniques', label: 'Techniques', position: 'left'},
          {to: '/contact', label: 'Contact', position: 'left'},
          {to: '/group-links', label: 'Links', position: 'left'},
          {
            href: 'https://github.com/deng-group',
            label: 'GitHub',
            position: 'right',
          },
          {
            href: 'https://matsci.dev',
            label: 'DENG.Group',
            position: 'right',
          },
        ],
      },
      footer: {
        style: 'dark',
        copyright: `© ${new Date().getFullYear()} Zeyu Deng. Built with Docusaurus.`,
      },
      prism: {
        additionalLanguages: ['powershell','bash','python','docker','latex','docker',],
        theme: prismThemes.github,
        darkTheme: prismThemes.dracula,
      },
      docs: {
        sidebar: {
          hideable: true,
          autoCollapseCategories: true,
        },
      },
    }),
};

Adding LaTex support for math equations and chemical formulas​

You can type LaTex math equations using $$ or $$ $$ and chemical formulas using $\ce{}$ in Docusaurus. Adding following to docusaurus.config.js:

import remarkMath from 'remark-math';
import rehypeKatex from 'rehype-katex';
require('katex/contrib/mhchem')

then also add following to the same file in the themeConfig block:

const config = {
  themeConfig:
    stylesheets: [
      {
        href: 'https://cdn.jsdelivr.net/npm/katex@0.13.24/dist/katex.min.css',
        type: 'text/css',
        integrity:
          'sha384-odtC+0UGzzFL/6PNoE8rX/SPcQDXBJ+uRepguP4QkPCm2LBxH3FA3y+fKSiJ+AmM',
        crossorigin: 'anonymous',
      },
    ],
};

Deploy the website on Cloudflare page​

The website is stored on Github and deployed on Cloudflare Page. You can use following steps to deploy it.

  1. Create a Github repository (can be private or public), and then push all the content in internal_website to this repository.
  2. Go to your Cloudflare portal: in Workers & Pages | Overview | Create application | Pages | Connect to Git. Then select your Github repository.
  3. Then you can add it to a domain name and wait it to be deployed.

Add Access control using Cloudflare Zero Trust​

You can add access control so that only certain people can access your website. For this website, I use Cloudflare Zero Trust for access control. Go to your Cloudflare portal, click Websites | YOURWEBSITES | Access | Launch Zero Trust for your Zero Trust portal.

Add authentication method​

I use Github OAuth App for authentication, so that I can allow people in a certain Github organization to have acecss to this website. To create a Github OAuth App, go to your Zero Trust portal, then click Settings | Authentication | Login methods | Add new. Follow the instructions on the right and create a Github OAuth App under your Github account.

Create access group​

In your Zero Trust portal, click Access | Access Groups | Add a Group. Set your group name and define your grouop. I use Github Organization as Selector and I choose my Github organization and team to access this group.

Create access application​

In your Zero Trust portal, click Access | Applications | Add an application | Overview, set the application name as Intranet, Session Duration, Application domain. Add Access policy: Under Access | Applications | Policies, add a policy. Set your name, Action to Allow, and then select the access group you set above. In Authentication, choose Github as your authentication methhod.