Docusaurus Access Restriction ~ Lockscreen Github Page

Introduction

As a context, Docusaurus is a static-site generator. It builds a single-page application with fast client-side navigation, leveraging the full power of React to make your site interactive. It provides out-of-the-box documentation features but can be used to create any kind of site (personal website, product, blog, marketing landing pages, etc).

Unfortunately, as Docusaurus generates static content, there’s no way for Docusaurus to add auth restrictions. This has to be done on the webserver layer which is beyond the scope of Docusaurus.

How about using Github Page?

Caution: This repository is private but the published site will be public.

Yes, you can easily change the access restriction with this documentation. But this feature is generally available today only on GitHub Enterprise Cloud.

Docusaurus Locksreen Starter

Introducing, docusaurus-lockscreen-starter, the starter that comes with a lock screen page by default. For setup & configuration, please follow the documentation here: https://github.com/coroo/docusaurus-lockscreen-starter.

You can see the demo at http://coroo.github.io/docusaurus-lockscreen-starter
*pass: secret

TLDR; Create Lockscreen From Scratch;

Ideas;

The idea for this solution came from the static page using SHA1 by matteobrusa at https://github.com/matteobrusa/Password-protection-for-static-pages.

Docusaurus Installation;

For easy installation using bootstrap, we can use

npx @docusaurus/init@latest init docusaurus-lockscren-starter bootstrap

You can see the full installation tutorial here.

After installation of docusaurus is completed, you can start the app by

cd docusaurus-lockscren-starter/
yarn install
yarn start

Setup Lockscreen Static Page;

First, we need to create a folder called lockscreen and add 2 static files index.html and style.css. So that, you will see the docusaurus foldering system:

➜  docusaurus-lockscren-starter tree -L 1
.
├── README.md
├── babel.config.js
├── blog/
├── docs/
├── docusaurus.config.js
├── lockscreen/
│   ├── index.html
│   └── style.css
├── node_modules/
├── package.json
├── sidebars.js
├── src/
├── static/
└── yarn.lock

Inside the lockscreen folder, create 2 static files stated before:

lockscreen/index.html

lockscreen/style.css

Add github action

For creating the page at github, we will use github action. First, need to setup the docusaurus.config.js by:

• import dotenv (install it first by yarn add dotenv)

const dotenv = require('dotenv');
dotenv.config();

• Change the url & baseUrl to get from theenvironment.

url: process.env.WIKI_URL,
baseUrl: process.env.WIKI_BASE_URL,

Then, we need to create an environment file in docusaurus-lockscren-starter folder.

./.env
WIKI_URL='https://coroo.github.io'
WIKI_GITHUB_URL='https://github.com/coroo/docusaurus-lockscren-starter'
ORGANIZATION_NAME='coroo'
PROJECT_NAME='docusaurus-lockscren-starter'

After that, you need to create a workflow file at
./.github/workflows/documentation.yml

.github/workflows/documentation.yaml

Ok, that's all. Next, we will create a new repository and push all the code to github.com and create a secret & deploy key.

Setup Deployment & Repository Secret Key

Deployment Key (id_rsa)

To get deployment & repository secret key, you can follow these steps:

https://gist.github.com/zhujunsan/a0becf82ade50ed06115

Repository Secret Key

We also need to add another environment that not mentioned at .env before to repository secret key. This way also make your page more secure since you stated the environment at github secret-key rather than at public .env.

1. As I mentioned above, we use a lock screen with SHA1 generator. To create your default password, you can use my password SHA1 generator at http://coroo.github.io/secret-generator/.
2. Go to your secret tab at your repository settings, add new repository secret.
   Add two actions secret:

PASSWORD={sha1-secret}
WIKI_BASE_URL=/{your-repository-name}/{sha1-secret}/
e.g.
PASSWORD=e5e9fa1ba31ecd1ae84f75caaa474f3a663f05f4
WIKI_BASE_URL=/docusaurus-lockscreen-starter/e5e9fa1ba31ecd1ae84f75caaa474f3a663f05f4/

Repository Secrets Key

Deployed

Check your action tab in your repository, and check if any deployment running, if not, edit your readme and push again to your github repository. Your site should be deployed within 1–10minutes.

Only after 10 minutes your page not yet created, go to Settings — Pages and update the default branch to gh-pages:

Source: GH-Pages

Conclusion

Docusaurus is a static page generator that can help you and your team to save time and focus on your project’s documentation. Simply write docs and blog posts with Markdown/MDX and Docusaurus will publish a set of static HTML files ready to serve. You can even embed JSX components into your Markdown thanks to MDX.

Also, although for now docusaurus doesn’t have and doesn’t plan to have featured for securing the page, we still can secure this documentation by using the static page just mentioned above.

Hopefully, this article can help you and your team create a secure github page and enjoy to continue writing docs & blogs with docusaurus.

Last but not least

By securing the page using SHA1, it’s better that you replace the password and wiki_base_url at the repository secrets periodically to avoid unwanted things.