Skip to content

Commit 43436fe

Browse files
jdeniaujdeniau
committed
start mdx documentation
1 parent 8240325 commit 43436fe

File tree

12 files changed

+203
-35
lines changed

12 files changed

+203
-35
lines changed

‎website/docs/mergeDeep().mdx

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
import Repl from '@/repl/Repl.tsx';
2+
3+
# mergeDeep()
4+
5+
Like [`merge()`](<../merge()>), but when two compatible collections are encountered with
6+
the same key, it merges them as well, recursing deeply through the nested
7+
data. Two collections are considered to be compatible (and thus will be
8+
merged together) if they both fall into one of three categories: keyed
9+
(e.g., [`Map`](../Map)s, [`Record`](../Record)s, and objects), indexed (e.g., [`List`](../List)s and
10+
arrays), or set-like (e.g., [`Set`](../Set)s). If they fall into separate
11+
categories, [`mergeDeep`](<../mergeDeep()>) will replace the existing collection with the
12+
collection being merged in. This behavior can be customized by using
13+
[`mergeDeepWith()`](<../mergeDeepWith()>).
14+
15+
<Signature code={`mergeDeep(collection, ...collections)`} />
16+
17+
Note: Indexed and set-like collections are merged using
18+
`concat()`/`union()` and therefore do not recurse.
19+
20+
A functional alternative to `collection.mergeDeep()` which will also work
21+
with plain Objects and Arrays.
22+
23+
<Repl defaultValue={`List(['a', 'b', 'c'])`} />
24+
25+
// TODO this should be in the repl but it does have an error
26+
27+
```js
28+
const original = { x: { y: 123 } };
29+
mergeDeep(original, { x: { z: 456 } }); // { x: { y: 123, z: 456 }}
30+
console.log(original); // { x: { y: 123 }}
31+
```

‎website/src/app/docs/v5/mergeDeepWith()/page.mdx renamed to ‎website/docs/mergeDeepWith().mdx

Lines changed: 22 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,29 +1,36 @@
11
import Repl from '@/repl/Repl.tsx';
22

3-
Like `mergeDeep()`, but when two non-collections or incompatible
3+
# mergeDeepWith()
4+
5+
Like[`mergeDeep()`](<../mergeDeep()>), but when two non-collections or incompatible
46
collections are encountered at the same key, it uses the `merger` function
57
to determine the resulting value. Collections are considered incompatible
68
if they fall into separate categories between keyed, indexed, and set-like.
79

10+
<Signature
11+
code={`mergeDeepWith(
12+
merger: (oldVal, newVal, key) => any,
13+
collection,
14+
...collections
15+
)`}
16+
/>
17+
818
A functional alternative to `collection.mergeDeepWith()` which will also
919
work with plain Objects and Arrays.
1020

11-
```js
12-
import { mergeDeepWith } from 'immutable';
13-
const original = { x: { y: 123 } };
14-
15-
mergeDeepWith((oldVal, newVal) => oldVal + newVal, original, { x: { y: 456 } }); // { x: { y: 579 }}
21+
<Repl
22+
defaultValue={`List([1, 2, 3])
23+
`}
24+
/>
1625

17-
console.log(original); // { x: { y: 123 }}
18-
```
26+
// TODO this should be in the repl but it does have an error
1927

20-
```
28+
```js
2129
const original = { x: { y: 123 } };
2230

23-
mergeDeepWith((oldVal, newVal) => oldVal + newVal, original, { x: { y: 456 } });
31+
mergeDeepWith(
32+
(oldVal, newVal) => oldVal + newVal,
33+
original,
34+
{ x: { y: 456 }
35+
);
2436
```
25-
26-
<Repl
27-
defaultValue={`List([1, 2, 3])
28-
`}
29-
/>

‎website/src/TypeDocumentation.tsx

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -75,7 +75,7 @@ export function TypeDocumentation({
7575
function FunctionDoc({ def }: { def: MemberDefinition }) {
7676
return (
7777
<div>
78-
<h1 className="typeHeader">{def.label}</h1>
78+
<h1>{def.label}</h1>
7979
{def.doc && (
8080
<MarkdownContent className="docSynopsis" contents={def.doc.synopsis} />
8181
)}
@@ -128,7 +128,7 @@ function TypeDoc({
128128

129129
return (
130130
<div>
131-
<h1 className="typeHeader">{def.qualifiedName}</h1>
131+
<h1>{def.qualifiedName}</h1>
132132
{def.doc && (
133133
<MarkdownContent className="docSynopsis" contents={def.doc.synopsis} />
134134
)}

‎website/src/app/docs/[version]/page.tsx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ export default async function OverviewDocPage(props: Props) {
4040
<SideBar links={sidebarLinks} />
4141
<div key="Overview" className="docContents">
4242
<DocSearch />
43-
<h1>Immutable.js ({version})</h1>
43+
<h1 className="mainTitle">Immutable.js ({version})</h1>
4444
<DocOverview data={overviewData} />
4545
</div>
4646
</>

‎website/src/app/docs/v5/[type]/page.tsx

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
import { getDocFiles } from '@/utils/doc';
2+
3+
export async function generateStaticParams() {
4+
const docFiles = getDocFiles();
5+
6+
return docFiles.map((file) => ({
7+
type: file.slug,
8+
}));
9+
}
10+
11+
type Params = {
12+
version: string;
13+
type: string;
14+
};
15+
16+
type Props = {
17+
params: Promise<Params>;
18+
};
19+
20+
export async function generateMetadata(props: Props) {
21+
const params = await props.params;
22+
23+
console.log('params', params);
24+
25+
return {
26+
title: `${params.type} — Immutable.js`,
27+
};
28+
}
29+
30+
export default async function TypeDocPage(props: Props) {
31+
const params = await props.params;
32+
33+
const { type } = params;
34+
35+
const { default: MdxContent } = await import(`@/docs/${type}.mdx`);
36+
37+
return <MdxContent />;
38+
}

‎website/src/app/docs/v5/layout.tsx

Lines changed: 15 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,8 @@
1+
import { SideBar } from '@/Sidebar';
2+
import { DocSearch } from '@/DocSearch';
13
import { DocHeader } from '../../../DocHeader';
24
import { ImmutableConsole } from '../../../ImmutableConsole';
35
import { getVersions } from '../../../static/getVersions';
4-
import { getVersionFromParams } from '../../getVersionFromParams';
56

67
export default async function VersionLayout(props: {
78
children: React.ReactNode;
@@ -15,14 +16,25 @@ export default async function VersionLayout(props: {
1516

1617
const version = 'v5';
1718

19+
// TODO get the real links from the file list
20+
const sidebarLinks = [
21+
{ label: 'List', url: `/docs/${version}/List` },
22+
{ label: 'mergeDeep()', url: `/docs/${version}/mergeDeep()` },
23+
{ label: 'mergeDeepWith()', url: `/docs/${version}/mergeDeepWith()` },
24+
];
25+
1826
return (
1927
<div>
2028
<ImmutableConsole version={version} />
2129
<DocHeader versions={versions} currentVersion={version} />
2230
<div className="pageBody">
2331
<div className="contents">
24-
<div>sidebar</div>
25-
<div className="docContents">{children}</div>
32+
<SideBar links={sidebarLinks} />
33+
34+
<div className="docContents">
35+
<DocSearch />
36+
{children}
37+
</div>
2638
</div>
2739
</div>
2840
</div>

‎website/src/mdx-components.tsx

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,53 @@
11
import type { MDXComponents } from 'mdx/types';
2+
import Prism from 'prismjs';
3+
import loadLanguages from 'prismjs/components/';
4+
5+
loadLanguages(['ts']);
26

37
export function useMDXComponents(components: MDXComponents): MDXComponents {
48
return {
9+
code: ({ className, children, ...rest }) => {
10+
if (!className) {
11+
// no classname : no need to handle syntax highlighting
12+
return <code {...rest}>{children}</code>;
13+
}
14+
15+
const language = className.replace('language-', '');
16+
const html = Prism.highlight(
17+
String(children).trim(),
18+
Prism.languages[language] || Prism.languages.plaintext,
19+
language
20+
);
21+
22+
return (
23+
<code
24+
className={`codeBlock language-${language}`}
25+
dangerouslySetInnerHTML={{ __html: html }}
26+
{...rest}
27+
/>
28+
);
29+
},
30+
Signature: ({ code }) => {
31+
const language = 'ts';
32+
console.log(code);
33+
const html = Prism.highlight(
34+
String(code).trim(),
35+
Prism.languages[language],
36+
language
37+
);
38+
39+
return (
40+
<div>
41+
<h4>Method signature</h4>
42+
<pre>
43+
<code
44+
className="codeBlock memberSignature"
45+
dangerouslySetInnerHTML={{ __html: html }}
46+
/>
47+
</pre>
48+
</div>
49+
);
50+
},
551
...components,
652
};
753
}

‎website/src/repl/Repl.tsx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,7 @@ function Repl({ defaultValue, onRun }: Props): JSX.Element {
6565
</button>
6666
</div>
6767

68-
<pre id="output">
68+
<pre className="repl-output">
6969
<FormatterOutput output={output} />
7070
</pre>
7171
</div>

‎website/src/repl/repl.css

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@
1111
border: 1px solid var(--code-block-bg-color);
1212
}
1313

14-
textarea {
14+
.js-repl textarea {
1515
width: 100%;
1616
height: 100px;
1717
margin-bottom: 10px;
@@ -23,7 +23,7 @@ textarea {
2323
resize: none;
2424
}
2525

26-
button {
26+
.js-repl button {
2727
padding: 10px 15px;
2828
font-size: 14px;
2929
background-color: var(--link-color);
@@ -33,11 +33,11 @@ button {
3333
cursor: pointer;
3434
}
3535

36-
button:hover {
36+
.js-repl button:hover {
3737
background-color: var(--link-hover-color);
3838
}
3939

40-
pre {
40+
.js-repl pre.repl-output {
4141
background-color: var(--code-block-bg-color);
4242
padding: 10px;
4343
border: 1px solid #ccc;

‎website/src/utils/doc.tsx

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
import fs from 'node:fs';
2+
import path from 'node:path';
3+
4+
function getMDXFiles(dir: string): Array<string> {
5+
return fs.readdirSync(dir).filter((file) => path.extname(file) === '.mdx');
6+
}
7+
8+
function getMDXData(dir: string): Array<{ slug: string }> {
9+
const files = getMDXFiles(dir);
10+
11+
console.log('files', files);
12+
13+
return files.map((file) => {
14+
const slug = path.basename(file, path.extname(file));
15+
16+
return {
17+
slug,
18+
};
19+
});
20+
}
21+
22+
export function getDocFiles() {
23+
const docsDir = path.join(process.cwd(), 'docs');
24+
25+
return getMDXData(docsDir);
26+
}

‎website/styles/globals.css

Lines changed: 16 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,18 @@ h6 {
6464
color: var(--header-color);
6565
}
6666

67+
h1 {
68+
color: light-dark(#555, #fff);
69+
font-size: 1.5em;
70+
margin: 1rem 0;
71+
font-weight: bold;
72+
}
73+
74+
h1.mainTitle {
75+
font-size: 2em;
76+
margin: 1.34rem 0;
77+
}
78+
6779
h2 {
6880
margin: 4rem 0 1rem;
6981
}
@@ -76,7 +88,8 @@ h4 {
7688
margin: 1rem 0 0;
7789
}
7890

79-
a {
91+
a,
92+
a > code {
8093
color: var(--link-color);
8194
text-decoration: none;
8295
}
@@ -116,6 +129,7 @@ blockquote > :last-child {
116129

117130
/* Markdown */
118131

132+
pre > code,
119133
.codeBlock {
120134
-webkit-overflow-scrolling: touch;
121135
background: var(--code-block-bg-color);
@@ -174,6 +188,7 @@ a.try-it {
174188

175189
.contents > .docContents {
176190
flex-grow: 1;
191+
max-width: calc(1024px - 340px); /* contents width minus sidebar */
177192
}
178193

179194
img {
@@ -518,14 +533,6 @@ img {
518533
background-color: rgba(112, 170, 220, 0.2);
519534
}
520535

521-
.typeHeader {
522-
color: light-dark(#555, #fff);
523-
font-size: 1.5em;
524-
font-weight: normal;
525-
margin: 1rem 0;
526-
font-weight: bold;
527-
}
528-
529536
.interfaceMember {
530537
padding-top: 4rem;
531538
margin-top: -5rem;

‎website/tsconfig.json

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@
1616
"incremental": true,
1717
"baseUrl": "src/",
1818
"paths": {
19+
"@/docs/*": ["../docs/*"],
1920
"@/*": ["./*"]
2021
},
2122
"plugins": [

0 commit comments

Comments
 (0)