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.
Initilizing projectโ
- With repo with nx
npx create-nx-workspace@latest <project_name> --preset=ts
- Update
package.json
to use pnpm
{
"name": "<project_name>",
"engine": {
"node": "^20",
"pnpm": ">=8"
}
}
- Change
package-lock.json
file into pnpm-lock.yaml
file
Adding git submoduleโ
- Move into the project
- 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โ
- Create a public repo.
- Go to repo setting.
- In the left section, there we will find Pages section.
- Scroll to Build and deployment section
- Select from Deploy from a branch
- Select Branch - main and folder - root
- 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>",
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 ๐