Skip to content

Commit bf7872b

Browse files
ajay-dhangarajay-dhangar
authored
Merge pull request #4853 from codeharborhub/dev-5-1
Added Advance guide doc
2 parents 2598537 + 96fca06 commit bf7872b

File tree

12 files changed

+785
-1
lines changed

12 files changed

+785
-1
lines changed

‎docs/advanced/architecture.mdx‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
---
2+
title: Architecture
3+
description: "How CodeHarborHub’s documentation engine and architecture work together to build your site"
4+
---
5+
6+
```mdx-code-block
7+
import Zoom from 'react-medium-image-zoom';
8+
import 'react-medium-image-zoom/dist/styles.css';
9+
```
10+
11+
<Zoom>
12+
13+
![Architecture overview](/img/architecture.png)
14+
15+
</Zoom>
16+
17+
This diagram explains how **CodeHarborHub’s documentation system** (powered by Docusaurus) works under the hood to build and serve your learning platform. Each **plugin** is responsible for collecting and processing content (like docs, tutorials, or blogs) and emitting structured JSON data.
18+
19+
The **themes** provide the layout and UI components that transform this JSON data into dynamic, interactive web pages.
20+
21+
The **bundler** then takes care of packaging everything—building both the **server** and **client** bundles that power the entire site experience.
22+
23+
---
24+
25+
## Key Architectural Layers
26+
27+
### 1. Plugin Layer
28+
29+
Plugins manage content and configuration. Each plugin runs entirely in **Node.js**, processing Markdown, MDX, and metadata into structured JSON.
30+
31+
For example:
32+
- The **Docs Plugin** gathers all your course and guide files.
33+
- The **Blog Plugin** handles educational blog content.
34+
- The **Pages Plugin** renders custom pages like `/about`, `/events`, or `/community`.
35+
36+
All plugin lifecycle methods run in **Node**. That means plugin code must be written in **CommonJS** (using `require`) or **ES Modules** (using `import/export`) that Node can execute.
37+
38+
---
39+
40+
### 2. Theme Layer
41+
42+
Themes define how the content looks and feels. Theme components are written in **React**, built with **Webpack**, and rendered on the client side.
43+
44+
They receive the JSON output from plugins and render them as complete pages—
45+
such as documentation layouts, course cards, contributor profiles, and interactive learning modules.
46+
47+
**Themes and plugins don’t directly import or depend on each other.**
48+
They communicate through **JSON data** and **route configuration**, ensuring modularity and scalability.
49+
50+
A useful way to think about it:
51+
> Imagine plugins are written in another language (like Rust or Go) — they just output structured data.
52+
> The theme is the visual layer that interprets and displays that data beautifully.
53+
54+
---
55+
56+
### 3. Configuration Layer
57+
58+
Your `docusaurus.config.js` (or `docusaurus.config.mjs`) connects everything.
59+
60+
It runs in **Node.js** and defines:
61+
- Global settings like `title`, `url`, `baseUrl`, and `favicon`
62+
- Plugin and theme configurations
63+
- Site metadata, SEO tags, and integration settings
64+
65+
You can pass callbacks or dynamic logic to plugins here.
66+
However, only **serializable values** (those that survive `JSON.stringify()`) make it to the client.
67+
68+
This means:
69+
- ✅ Strings, numbers, arrays, and objects are preserved
70+
- ⚠️ Functions, regexes, and complex data structures are lost in the browser bundle
71+
72+
During bundling, the configuration file is serialized and injected into the client bundle, allowing the site to access global data via:
73+
74+
```js
75+
import { useDocusaurusContext } from '@docusaurus/core';
76+
77+
const { siteConfig } = useDocusaurusContext();
78+
console.log(siteConfig.themeConfig);
79+
```
80+
81+
---
82+
83+
## Summary of the Build Process
84+
85+
| Stage | Environment | Responsibility |
86+
|--------|--------------|----------------|
87+
| **Plugins** | Node.js | Collect content and generate JSON data |
88+
| **Themes** | Browser + Webpack | Render JSON data into UI components |
89+
| **Bundler** | Build (Webpack/Vite) | Output optimized server and client bundles |
90+
| **Config** | Node.js | Define site structure and plugin options |
91+
92+
---
93+
94+
## Why This Matters for CodeHarborHub
95+
96+
This architecture allows CodeHarborHub to be:
97+
- ⚡ **Fast and modular** — each content type (Docs, Blogs, Events) acts independently
98+
- 🧠 **Extensible** — easily add new learning modules or plugins
99+
- 🌐 **Universal** — supports versioning, localization, and custom themes
100+
- 🔒 **Safe and scalable** — clean separation between content, configuration, and rendering
101+
102+
---

‎docs/advanced/client.mdx‎

Lines changed: 197 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,197 @@
1+
---
2+
title: Client Architecture
3+
description: Understanding how the CodeHarborHub client system works
4+
---
5+
6+
The **client architecture** of CodeHarborHub (built on Docusaurus) defines how the front-end interacts with React components, themes, and client-side modules. It focuses on modularity, performance, and extensibility — allowing you to customize your learning platform’s UI and logic.
7+
8+
---
9+
10+
## Theme Aliases {#theme-aliases}
11+
12+
Themes in CodeHarborHub work by exporting a set of **React components** such as `Navbar`, `Layout`, and `Footer`. These components render structured data provided by plugins.
13+
14+
They are imported using the Webpack alias `@theme`:
15+
16+
```js
17+
import Navbar from '@theme/Navbar';
18+
```
19+
20+
### How it works
21+
22+
The `@theme` alias points to several possible directories in this order of priority:
23+
24+
1. `website/src/theme` — The **user’s custom theme directory** (highest priority).
25+
2. `node_modules/@docusaurus/theme-*` — Theme package components.
26+
3. Core fallback components provided by Docusaurus (least used).
27+
28+
This creates a **layered architecture** — higher layers override lower ones.
29+
For example:
30+
31+
```
32+
website
33+
├── node_modules
34+
│ └── @docusaurus/theme-classic
35+
│ └── theme
36+
│ └── Navbar.js
37+
└── src
38+
└── theme
39+
└── Navbar.js
40+
```
41+
42+
Here, `website/src/theme/Navbar.js` takes precedence whenever you import `@theme/Navbar`. This concept is known as **swizzling** — overriding or extending existing components.
43+
44+
### Wrapping and Extending Components
45+
46+
If you want to extend a theme component instead of replacing it, use:
47+
48+
- `@theme-original` — Imports the next component down the stack.
49+
- `@theme-init` — Imports the base implementation from the original theme.
50+
51+
Example: enhancing a `CodeBlock` component with a live playground:
52+
53+
```js
54+
import InitialCodeBlock from '@theme-init/CodeBlock';
55+
import React from 'react';
56+
import ReactLivePlayground from '@theme/ReactLivePlayground';
57+
58+
export default function CodeBlock(props) {
59+
return props.live ? (
60+
<ReactLivePlayground {...props} />
61+
) : (
62+
<InitialCodeBlock {...props} />
63+
);
64+
}
65+
```
66+
67+
:::warning
68+
Unless you’re building a reusable theme (like `@docusaurus/theme-live-codeblock`), you won’t usually need `@theme-init`.
69+
:::
70+
71+
### Visualization of Theme Stack
72+
73+
Internally, CodeHarborHub loads components as a “stack” of layers:
74+
75+
```text
76+
+-------------------------------------------------+
77+
| website/src/theme/CodeBlock.js | <-- @theme/CodeBlock
78+
+-------------------------------------------------+
79+
| theme-live-codeblock/theme/CodeBlock/index.js | <-- @theme-original/CodeBlock
80+
+-------------------------------------------------+
81+
| plugin-awesome-codeblock/theme/CodeBlock.js |
82+
+-------------------------------------------------+
83+
| theme-classic/theme/CodeBlock/index.js | <-- @theme-init/CodeBlock
84+
+-------------------------------------------------+
85+
```
86+
87+
The **site layer** (`src/theme`) always takes precedence since it’s loaded last.
88+
89+
---
90+
91+
## Client Modules {#client-modules}
92+
93+
Client modules are **global scripts or styles** that run before React renders your site. They include JS and CSS that modify global state, register event listeners, or add global styling.
94+
95+
Under the hood:
96+
97+
```js title="@docusaurus/core/App.tsx"
98+
import '@generated/client-modules';
99+
```
100+
101+
### Declaring Client Modules
102+
103+
Plugins and sites can declare client modules using:
104+
105+
- [`getClientModules`](https://docusaurus.io/docs/api/plugin-methods/lifecycle-apis#getClientModules)
106+
- [`siteConfig.clientModules`](https://docusaurus.io/docs/api/docusaurus-config#clientModules)
107+
108+
These modules are imported globally and executed both during server-side rendering (SSR) and client-side hydration.
109+
110+
Example of a client-side script:
111+
112+
```js title="mySiteGlobalJs.js"
113+
import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';
114+
115+
if (ExecutionEnvironment.canUseDOM) {
116+
window.addEventListener('keydown', (e) => {
117+
if (e.code === 'Period') {
118+
location.assign(location.href.replace('.com', '.dev'));
119+
}
120+
});
121+
}
122+
```
123+
124+
Example of global CSS:
125+
126+
```css title="mySiteGlobalCss.css"
127+
/* Global stylesheet */
128+
.globalSelector {
129+
color: #007bff;
130+
font-weight: bold;
131+
}
132+
```
133+
134+
---
135+
136+
## Client Module Lifecycles {#client-module-lifecycles}
137+
138+
Client modules can define **lifecycle functions** to handle route transitions in your single-page app (SPA).
139+
140+
### Available Lifecycle Methods
141+
142+
- `onRouteUpdate`: triggered when navigation starts
143+
- `onRouteDidUpdate`: triggered after the new route has rendered
144+
145+
These functions receive `{ location, previousLocation }` as parameters.
146+
147+
Example:
148+
149+
```js title="myClientModule.js"
150+
export function onRouteDidUpdate({location, previousLocation}) {
151+
if (location.pathname !== previousLocation?.pathname) {
152+
const title = document.querySelector('h1');
153+
if (title) title.innerText += ' 🚀';
154+
}
155+
}
156+
157+
export function onRouteUpdate({location, previousLocation}) {
158+
if (location.pathname !== previousLocation?.pathname) {
159+
const progress = setTimeout(() => {
160+
nprogress.start();
161+
}, 200);
162+
return () => clearTimeout(progress);
163+
}
164+
}
165+
```
166+
167+
TypeScript version:
168+
169+
```ts title="myClientModule.ts"
170+
import type {ClientModule} from '@docusaurus/types';
171+
172+
const module: ClientModule = {
173+
onRouteUpdate({location, previousLocation}) {
174+
// Custom navigation logic
175+
},
176+
onRouteDidUpdate({location, previousLocation}) {
177+
// DOM manipulations or analytics
178+
},
179+
};
180+
181+
export default module;
182+
```
183+
184+
Both lifecycles run on the **client side only** and are safe for accessing browser globals.
185+
186+
---
187+
188+
:::tip Prefer React-based Implementations
189+
190+
If your feature depends on **state**, **hooks**, or **context**,
191+
it’s better to use [component swizzling](https://docusaurus.io/docs/swizzling#wrapping) instead of client modules.
192+
Client modules are ideal for simple global effects, not for complex UI logic.
193+
:::
194+
195+
---
196+
197+
By understanding **theme aliases** and **client modules**, you can fully control CodeHarborHub’s front-end architecture — blending flexibility, modular design, and smooth client-side experiences.

‎docs/advanced/index.mdx‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
---
2+
title: Advanced Tutorials
3+
---
4+
5+
Welcome to the **Advanced Tutorials** section of CodeHarborHub!
6+
Here, we dive deeper into the architecture, performance optimization, and real-world integrations that power modern web applications.
7+
8+
This section may not be as structured as the beginner guides, but it will cover advanced and practical topics including:
9+
10+
- Advanced component architecture
11+
- Plugin and theme development
12+
- Performance and SEO optimization
13+
- Deployment strategies
14+
- Integrations with AI and backend services
15+
16+
```mdx-code-block
17+
import DocCardList from '@theme/DocCardList';
18+
19+
<DocCardList />
20+
```
21+
22+
We assume you’ve completed the fundamental guides and understand the basics — such as configuring plugins, writing React components, and structuring Docusaurus pages.
23+
24+
These tutorials are designed for **plugin authors**, **core contributors**, and **advanced developers**, so you’ll occasionally see references to internal APIs or low-level architecture details.
25+
26+
Don’t worry if everything doesn’t click right away — take your time, experiment, and explore! 🚀

0 commit comments

Comments
 (0)