Skip to content

Commit b098a44

Browse files
avivkelleravivkeller
authored
feat(ui): more custom components (#677)
1 parent c83af18 commit b098a44

7 files changed

Lines changed: 80 additions & 45 deletions

File tree

‎src/generators/jsx-ast/utils/buildContent.mjs‎

Lines changed: 4 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -293,25 +293,10 @@ export const createDocumentLayout = (
293293
remark
294294
) =>
295295
createTree('root', [
296-
createJSXElement(JSX_IMPORTS.NavBar.name),
297-
createJSXElement(JSX_IMPORTS.Article.name, {
298-
children: [
299-
createJSXElement(JSX_IMPORTS.SideBar.name, sideBarProps),
300-
createElement('div', [
301-
createElement('div', [
302-
createJSXElement(JSX_IMPORTS.TableOfContents.name, {
303-
headings: metaBarProps.headings,
304-
summaryTitle: 'On this page',
305-
}),
306-
createElement('br'),
307-
createElement(
308-
'main',
309-
entries.map(entry => processEntry(entry, remark))
310-
),
311-
]),
312-
createJSXElement(JSX_IMPORTS.MetaBar.name, metaBarProps),
313-
]),
314-
],
296+
createJSXElement(JSX_IMPORTS.Layout.name, {
297+
sideBarProps,
298+
metaBarProps,
299+
children: entries.map(entry => processEntry(entry, remark)),
315300
}),
316301
]);
317302

‎src/generators/web/README.md‎

Lines changed: 28 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,31 @@ The `web` generator transforms JSX AST entries into complete web bundles, produc
66

77
The `web` generator accepts the following configuration options:
88

9-
| Name | Type | Default | Description |
10-
| -------------- | -------- | ------------------------------------ | ------------------------------------------------------------------------ |
11-
| `output` | `string` | - | The directory where HTML, JavaScript, and CSS files will be written |
12-
| `templatePath` | `string` | `'template.html'` | Path to the HTML template file |
13-
| `imports` | `object` | `{ '#config/Logo': [Node.js Logo] }` | Object mapping import aliases to package names for external dependencies |
9+
| Name | Type | Default | Description |
10+
| -------------- | -------- | ----------------- | --------------------------------------------------------------------- |
11+
| `output` | `string` | - | The directory where HTML, JavaScript, and CSS files will be written |
12+
| `templatePath` | `string` | `'template.html'` | Path to the HTML template file |
13+
| `imports` | `object` | See below | Object mapping `#theme/` aliases to component paths for customization |
14+
15+
#### Default `imports`
16+
17+
| Alias | Default | Description |
18+
| ------------------- | -------------------------------------------- | -------------------------------------------- |
19+
| `#theme/Logo` | `@node-core/ui-components/Common/NodejsLogo` | Logo rendered inside the navigation bar |
20+
| `#theme/Navigation` | Built-in `NavBar` component | Top navigation bar |
21+
| `#theme/Sidebar` | Built-in `SideBar` component | Sidebar with version selector and page links |
22+
| `#theme/Layout` | Built-in `Layout` component | Outermost wrapper around the full page |
23+
24+
Override any alias in your config file to swap in a custom component:
25+
26+
```js
27+
// doc-kit.config.mjs
28+
export default {
29+
web: {
30+
imports: {
31+
'#theme/Logo': './src/MyLogo.jsx',
32+
'#theme/Sidebar': './src/MySidebar.jsx',
33+
},
34+
},
35+
};
36+
```

‎src/generators/web/constants.mjs‎

Lines changed: 3 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -23,17 +23,9 @@ export const NODE_MODULES = resolve(
2323
* An object containing mappings for various JSX components to their import paths.
2424
*/
2525
export const JSX_IMPORTS = {
26-
NavBar: {
27-
name: 'NavBar',
28-
source: resolve(ROOT, './ui/components/NavBar'),
29-
},
30-
SideBar: {
31-
name: 'SideBar',
32-
source: resolve(ROOT, './ui/components/SideBar'),
33-
},
34-
MetaBar: {
35-
name: 'MetaBar',
36-
source: resolve(ROOT, './ui/components/MetaBar'),
26+
Layout: {
27+
name: 'Layout',
28+
source: '#theme/Layout',
3729
},
3830
CodeBox: {
3931
name: 'CodeBox',
@@ -58,10 +50,6 @@ export const JSX_IMPORTS = {
5850
isDefaultExport: false,
5951
source: '@node-core/ui-components/MDX/Tooltip',
6052
},
61-
TableOfContents: {
62-
name: 'TableOfContents',
63-
source: '@node-core/ui-components/Common/TableOfContents',
64-
},
6553
ChangeHistory: {
6654
name: 'ChangeHistory',
6755
source: '@node-core/ui-components/Common/ChangeHistory',
@@ -70,10 +58,6 @@ export const JSX_IMPORTS = {
7058
name: 'AlertBox',
7159
source: '@node-core/ui-components/Common/AlertBox',
7260
},
73-
Article: {
74-
name: 'Article',
75-
source: '@node-core/ui-components/Containers/Article',
76-
},
7761
Blockquote: {
7862
name: 'Blockquote',
7963
source: '@node-core/ui-components/Common/Blockquote',

‎src/generators/web/index.mjs‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,12 @@ export default createLazyGenerator({
3030
templatePath: join(import.meta.dirname, 'template.html'),
3131
title: 'Node.js',
3232
imports: {
33-
'#config/Logo': '@node-core/ui-components/Common/NodejsLogo',
33+
'#theme/Logo': '@node-core/ui-components/Common/NodejsLogo',
34+
'#theme/Navigation': join(import.meta.dirname, './ui/components/NavBar'),
35+
'#theme/Sidebar': join(import.meta.dirname, './ui/components/SideBar'),
36+
'#theme/Metabar': join(import.meta.dirname, './ui/components/MetaBar'),
37+
'#theme/Footer': join(import.meta.dirname, './ui/components/NoOp'),
38+
'#theme/Layout': join(import.meta.dirname, './ui/components/Layout'),
3439
},
3540
},
3641
});

‎src/generators/web/ui/components/Layout/index.jsx‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
import TableOfContents from '@node-core/ui-components/Common/TableOfContents';
2+
import Article from '@node-core/ui-components/Containers/Article';
3+
4+
import Footer from '#theme/Footer';
5+
import MetaBar from '#theme/Metabar';
6+
import NavBar from '#theme/Navigation';
7+
import SideBar from '#theme/Sidebar';
8+
9+
/**
10+
* Default page Layout component.
11+
*
12+
* Renders the full page structure: navigation, sidebar, table of contents,
13+
* main content, meta bar, and footer. Override via `#theme/Layout` in your
14+
* configuration's `imports` to customize the entire page structure.
15+
*
16+
* @param {{ sideBarProps: object, metaBarProps: object, children: import('preact').ComponentChildren }} props
17+
*/
18+
export default ({ sideBarProps, metaBarProps, children }) => (
19+
<>
20+
<NavBar />
21+
<Article>
22+
<SideBar {...sideBarProps} />
23+
<div>
24+
<div>
25+
<TableOfContents
26+
headings={metaBarProps.headings}
27+
summaryTitle="On this page"
28+
/>
29+
<br />
30+
<main>{children}</main>
31+
</div>
32+
<MetaBar {...metaBarProps} />
33+
</div>
34+
</Article>
35+
<Footer />
36+
</>
37+
);

‎src/generators/web/ui/components/NavBar.jsx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ import SearchBox from './SearchBox';
77
import { STATIC_DATA } from '../constants.mjs';
88
import { useTheme } from '../hooks/useTheme.mjs';
99

10-
import Logo from '#config/Logo';
10+
import Logo from '#theme/Logo';
1111

1212
/**
1313
* NavBar component that displays the headings, search, etc.

‎src/generators/web/ui/components/NoOp.jsx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
export default () => null;

0 commit comments

Comments
 (0)