Skip to main content

Repository setup

· 3 min read
Abhishek Gowda

Background​

This is a documentation repository for my advent of code solution.

Motive behind this website, I tend to forget things which I've done. And when the similar problem arise that needs to be solved, I try to look into git history to find how I solved it. But never I've gotten a thing out of git history. (Which is completly my mistake)

I've 2 repositories, one for the actual code and the other for hosting the documentation. The actual code is hosted in a private repo and this repo is a public compiled docusaurus site. I'll elobrate how I've set this up.

Setup​

Initilizing project​

  1. With repo with nx
npx create-nx-workspace@latest <project_name> --preset=ts
  1. Update package.json to use pnpm
{
    "name": "<project_name>",
    "engine": {
        "node": "^20",
        "pnpm": ">=8"
    }
}
  1. Change package-lock.json file into pnpm-lock.yaml file
pnpm import

Adding git submodule​

  1. Move into the project
  2. Add submodule to the project, in this case we had already created a different empty repository for this.
git submodule add <repository_url>

With this there should be a new file called .gitmodules should be created. With the information about the module added.

At this point we can commit the progress.

Creating packages within the mono repo​

The root repo we have is a mono repo. Now we have to create a new file with name pnpm-workspace.yaml. Inside it added the folder structure. This is what I've

packages:
  - 'src/*'
  - 'documentation/*'

Creating docusaurus folder​

There is a generator for creating of docusaurus in nx. But I prefer using the create command from docusaurus.

npx create-docusaurus@latest documentation classic --typescript

With this the setup for the repository is completed.

Update docusaurus config​

There are couple of configuration changes that needs to be done in docusaurus.config file.

With this the setting up of documentation repo will be completed. But we still need to host this in github pages.

Hosting in github pages​

The submodule repo we added is a public github pages repo

Enabling github pages​

  1. Create a public repo.
  2. Go to repo setting.
  3. In the left section, there we will find Pages section.
  4. Scroll to Build and deployment section
  5. Select from Deploy from a branch
  6. Select Branch - main and folder - root
  7. Click on save.

It would take few seconds and the github page should be up.

There should be Visit site button. Click on it, will take to the deployed page. Copy the url of the page.

Go back to the Landing page of the repo.

In the right hand side there we will find a gear icon ⚙, click on it. And enable Use your Github pages website check box.

Conclusion​

With this we should have things read for deployment.

Let tweak some script in the documentation package.json copy build script command and paste it and rename it to build-github-pages

Update the command as

"build-github-page": "docusaurus build && cp -rf build/* <sub_module_location>", // update submodule location here

Now run the command pnpm build-github-page.

With this the submodule will be update.

Add the update files in the root repository and commit with appropriate message.

  • Traverse to the submodule directory.
  • Add all the files to git and push the changes.
  • After few seconds the github page will be updated with the changes.

🎉 We have successfully deployed docusaurus as github pages 🚀