Personal Blog Powered By Foam and Docusaurus

To maintain my blog, I decouple the blog content and the SSG into two distinct folders. If I try to switch to a different SSG in the future, this separation will facilitate a quick and seamless transition.

Project Structure

❯ tree -L 3
.
├── README.md
├── _layouts
├── _ssg
│   └── docusaurus
│       ├── babel.config.js
│       ├── build
│       ├── docusaurus.config.js
│       ├── package-lock.json
│       ├── package.json
│       ├── sidebars.js
│       ├── src
│       └── static
├── assets
├── attachments
├── blog
|-- code-snippets
|   |-- assembly
|   |-- c
|   |-- cpp
|   |-- docker-compose
|   |-- dockerfile
|   `-- python
└── docs

I also include my daily codebase repos into the code-snippets/ folder, including:

• assembly: https://github.com/liviaerxin/hello-assembly.git
• c: https://github.com/liviaerxin/hello-c.git
• cpp: https://github.com/liviaerxin/hello-cpp.git
• docker-compose: https://github.com/liviaerxin/hello-docker-compose.git
• docker: https://github.com/liviaerxin/hello-docker.git
• python: https://github.com/liviaerxin/hello-python.git

Tech Stacks

• Foam: knowledge management system for providing rich features in vscode.
  • Graph Visualization
  • Link Autocompletion
  • Sync links on file rename
  • Templates
  • Generate references for your wikilinks
  • ...
• Docusaurus: static site generator (SSG ) to build a static site from Foam knowledge content.
  • SEO friendly
  • Powered by MDX
  • Search
  • Document Versioning
  • Internationalization (i18n)
• GitHub Actions: deploy to GitHub Pages.

Get started

npm install --prefix _ssg/docusaurus
yarn --cwd _ssg/docusaurus

# dev
npm run start --prefix _ssg/docusaurus
yarn --cwd _ssg/docusaurus start

# prod
npm run build --prefix _ssg/docusaurus
yarn --cwd _ssg/docusaurus build

npm run serve --prefix _ssg/docusaurus -- --host 0.0.0.0
yarn --cwd _ssg/docusaurus serve --host 0.0.0.0

Foam: A personal knowledge management and sharing system for VSCode

Docusaurus: Easy to maintain open source documentation websites.

About Docusaurus

Submodules

First time,

git clone --recursive https://github.com/liviaerxin/liviaerxin.github.io.git

or

git clone https://github.com/liviaerxin/liviaerxin.github.io.git
cd liviaerxin.github.io.git
git submodule update --init --recursive

After first clone,

Pull the latest commits for submodules

git submodule foreach git pull

or

git submodule update --remote --rebase
#or
git submodule update --remote --merge

only git submodule update --remote will update all commits and check the latest commit of submodule but do not move the submodule main branch to the commit. So using --rebase or --merge to merge the main branch into the branch origin/main.

Pull the commits pointed by the parent repo for submodules

git submodule update

Swizzling

Here're @docusaurus/theme-classic components being customized by swizzling,

npm run swizzle @docusaurus/theme-classic BlogPostItem -- --wrap --typescript
npm run swizzle @docusaurus/theme-classic BlogPostItem/Footer/ReadMoreLink -- --eject --typescript
npm run swizzle @docusaurus/theme-classic BlogTagsPostsPage -- --eject --typescript
npm run swizzle @docusaurus/theme-classic SearchBar -- --eject --typescript

Layout

Grid | Infima

CSS Styles

Colors | Infima

I used the default colors shades from Infima.

Icon Management

Bootstrap Icons · Official open source SVG icon library for BootstrapBootstrapGitHubTwitterOpen CollectiveBootstrap

Font Awesome

Tabler Icons - 1400+ Open source free SVG icons

React SVG: How to use SVGs best in React - CopyCat Blog

Metadata Setting

📦 plugin-content-blog | Docusaurus

📦 plugin-content-docs | Docusaurus

Front Matter VS Code Extension

Introduction | Front Matter

Import Code from GitHub Repository

Docusaurus refer code snippets from GitHub repositories

GitHub - saucelabs/docusaurus-theme-github-codeblock: A Docusaurus v2 plugin that supports referencing code examples from public GitHub repositories.

References

To be admit I am not good at UI design and development, however there many excellent docusaurus showcase in open source.

Thanks to tinaeldevresse, I got ideas to design my blog website by referring his blog library.

Changelogs

20240514

After several quiet months without maintaining my site and writing new posts, today I update my Docusaurus version from 2.4.3 to 3.3.2. It feels like a significant leap with many breaking changes. Let me try!

20241005

As I create more and more Git repositories, it's becoming increasingly difficult to keep track of them all, especially the ones I haven't used in over six months. I'm prone to forgetting about them. However, since this repository, my personal repository, is where I work in my daily life, I've decided to consolidate my other Git repositories into this one for quick reference when needed.