Skip to content
This repository was archived by the owner on Mar 10, 2023. It is now read-only.

Commit a19c3e9

Browse files
NovinyNoviny
authored
Noviny/add template option (#200)
* templates initial implementation * templates now receive page data and the page's component * add docs * changeset * fix linting + type errors * fix tests * tests tests * that * rename buildPagesPipeline * oh yeah
1 parent af01870 commit a19c3e9

File tree

20 files changed

+314
-43
lines changed

20 files changed

+314
-43
lines changed

‎.changeset/short-items-repair/changes.json

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
{
2+
"releases": [{ "name": "@brisk-docs/website", "type": "minor" }],
3+
"dependents": []
4+
}

‎.changeset/short-items-repair/changes.md

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
Add `template` option to pages
2+
3+
NB: initial implementation is only for `package:home` with other pages being added on request.

‎package.json

+1
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@
2323
"delete:dist": "bolt ws exec --parallel -- rm -rf dist",
2424
"delete:modules": "bolt ws exec --parallel -- rm -rf node_modules && rm -rf node_modules",
2525
"docs": "node packages/website/bin.js dev",
26+
"build:pages": "node packages/website/bin.js build-pages",
2627
"prettier": "prettier --write \"**/*.{js,ts,tsx}\"",
2728
"lint": "yarn lint:eslint && yarn lint:prettier && yarn check:types",
2829
"lint:prettier": "prettier --list-different \"**/*.{js,ts,tsx}\"",

‎packages/website/docs/configuration.md

+92-33
Original file line numberDiff line numberDiff line change
@@ -12,19 +12,20 @@ module.exports = () => ({
1212

1313
the returned object may have the following properties:
1414

15-
| Option | Description |
16-
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
17-
| customPackageFields | Array of fields from the relevant package.json to display on the package home page. This augments the default set. |
18-
| docs | Object (or array of Object) describing the project docs. |
19-
| favicon | Absolute path to an .ico file to use as the site's favicon e.g. `path.join(__dirname, 'favicon.ico')` |
20-
| links | Optional array of Object with links to display on the homepage |
21-
| packages | Path or array of paths of packages to show. Glob patterns are allowed. e.g. `path.join(__dirname, 'packages', '*')` |
22-
| packagesDescription | Optional String to replace the default description for the packages section |
23-
| readMePath | Optional String path to an alternative specific mdx file to use as the "Get Started" page. |
24-
| showExamples | Optional Boolean (default true) to include/exclude examples |
25-
| showSubExamples | Optional Boolean to include/exclude subExamples within packages |
26-
| siteName | String Display name for the project as displayed in the website |
27-
| webpack | A function used to customise the website's webpack configuration. see [Configuring webpack](./configuring-webpack) for more details |
15+
| Option | Description |
16+
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
17+
| customPackageFields | Array of fields from the relevant package.json to display on the package home page. This augments the default set. |
18+
| docs | Object (or array of Object) describing the project docs. |
19+
| favicon | Absolute path to an .ico file to use as the site's favicon e.g. `path.join(__dirname, 'favicon.ico')` |
20+
| links | Optional array of Object with links to display on the homepage |
21+
| packages | Path or array of paths of packages to show. Glob patterns are allowed. e.g. `path.join(__dirname, 'packages', '*')` |
22+
| packagesDescription | Optional String to replace the default description for the packages section |
23+
| readMePath | Optional String path to an alternative specific mdx file to use as the "Get Started" page. |
24+
| showExamples | Optional Boolean (default true) to include/exclude examples |
25+
| showSubExamples | Optional Boolean to include/exclude subExamples within packages |
26+
| siteName | String Display name for the project as displayed in the website |
27+
| templates | Set up templates for particular kinds of pages in brisk |
28+
| webpack | A function used to customise the website's webpack configuration. see [Configuring webpack](./configuring-webpack) for more details |
2829

2930
### customPackageFields
3031

@@ -38,6 +39,7 @@ e.g. `['author', 'dependencies']`
3839

3940
Type: optional `object` or `object[]`
4041
defaults to:
42+
4143
```js
4244
{
4345
path: './docs',
@@ -48,10 +50,10 @@ defaults to:
4850

4951
Object describing documentation sections
5052

51-
* `path`: `string` of the absolute path to the documentation section's directory e.g. `path.join(__dirname, 'docs')`
52-
* `name`: `string` to use for the documentation section e.g. `'Docs'`
53-
* `description`: Optional `string` description to refer to e.g. `'Documentation is contained within this section.'`
54-
* `urlPath`: Optional `string` specifying the URL subpath to use. e.g `'docs'`. If not supplied, this will be inferred from the directory name.
53+
- `path`: `string` of the absolute path to the documentation section's directory e.g. `path.join(__dirname, 'docs')`
54+
- `name`: `string` to use for the documentation section e.g. `'Docs'`
55+
- `description`: Optional `string` description to refer to e.g. `'Documentation is contained within this section.'`
56+
- `urlPath`: Optional `string` specifying the URL subpath to use. e.g `'docs'`. If not supplied, this will be inferred from the directory name.
5557

5658
For a given path, if it does not exist, that section will not be generated.
5759

@@ -71,24 +73,25 @@ Array of links to arbitrary places. These will be tiles at the end of all other
7173

7274
Each link has the following shape:
7375

74-
* `label`: `string` to display on the home page tile
75-
* `description`: Optional `string` to display on the home page tile
76-
* `href`: `string` full URL (to external site) or internal link e.g. `/packages`
76+
- `label`: `string` to display on the home page tile
77+
- `description`: Optional `string` to display on the home page tile
78+
- `href`: `string` full URL (to external site) or internal link e.g. `/packages`
7779

7880
e.g.
79-
```js
80-
[
81-
{
82-
label: 'Get accomplished today!',
83-
href: '/docco/guides/how-to-be-accomplished'
84-
},
85-
{
86-
label: 'Get a job!',
87-
description: 'Browse the available Atlassian career opportunities and join the team.',
88-
href: 'https://www.atlassian.com/company/careers/all-jobs'
89-
},
90-
]
9181

82+
```js
83+
[
84+
{
85+
label: 'Get accomplished today!',
86+
href: '/docco/guides/how-to-be-accomplished',
87+
},
88+
{
89+
label: 'Get a job!',
90+
description:
91+
'Browse the available Atlassian career opportunities and join the team.',
92+
href: 'https://www.atlassian.com/company/careers/all-jobs',
93+
},
94+
];
9295
```
9396

9497
### packages
@@ -143,7 +146,63 @@ e.g. `Fancy Docs`
143146

144147
Type: optional `Function` customizing webpack's configuration. Defaults to `identity`
145148

146-
See [Configuring webpack](./configuring-webpack) for more details.
149+
See [Configuring webpack](./configuring-webpack.md) for more details.
150+
151+
### templates
152+
153+
Type: optional `object[]` defaults to `[]`
154+
155+
Allows you to specify a component to be rendered on a page. This feature is still experimental.
156+
157+
To add a template to a page, you can add an object to the array of the shape
158+
159+
```json
160+
{
161+
// the page you want to display this template component ont
162+
"page": string,
163+
// the position you want to display the template component in
164+
"position": string,
165+
// a path to the component you wish to render
166+
"component": string
167+
}
168+
```
169+
170+
Current pages that support templates:
171+
172+
- `package:home`
173+
174+
Positions for template are: `above`, `below`, and `replace`
175+
176+
`component` accepts a string which is a path to a file we will load. We treat this file as a react component to load on the website.
177+
178+
We pass two props to this component: `data` and `pageComponent`. To get an idea of what is being passed, you could add the following component as a template.
179+
180+
```js
181+
import React from 'react';
182+
183+
export default ({ data }) => console.log(data) || null;
184+
```
185+
186+
You can also style the page contents using something such as:
187+
188+
```js
189+
import React from 'react';
190+
191+
export default ({ pageComponent: Component }) => (
192+
<div
193+
style={{
194+
textAlign: 'center',
195+
color: 'rebeccapurple',
196+
backgroundColor: 'hotpink',
197+
borderRadius: '16px',
198+
padding: '8px',
199+
marginTop: '16px',
200+
}}
201+
>
202+
<Component />
203+
</div>
204+
);
205+
```
147206

148207
## Nested configuration
149208

‎packages/website/dummy-data/complete-config-project/docs.config.js

+12
Original file line numberDiff line numberDiff line change
@@ -50,4 +50,16 @@ module.exports = () => ({
5050
},
5151
readMePath: path.join(__dirname, 'index.md'),
5252
readMeImgSrc: '/static/simplify.svg',
53+
templates: [
54+
{
55+
page: 'package:home',
56+
position: 'above',
57+
component: 'dummy-data/templates/package-home-extension',
58+
},
59+
{
60+
page: 'package:home',
61+
position: 'replace',
62+
component: 'dummy-data/templates/package-home-replacement',
63+
},
64+
],
5365
});

‎packages/website/dummy-data/templates/package-home-extension.tsx

+20
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
import React from 'react';
2+
3+
export default ({
4+
data,
5+
}: {
6+
data: { name: string; version: string };
7+
pageComponent: React.ElementType;
8+
}) =>
9+
// @ts-ignore
10+
console.log(data) || (
11+
<div
12+
style={{
13+
fontSize: '14px',
14+
}}
15+
>
16+
<code>
17+
npm install {data.name}@^{data.version}
18+
</code>
19+
</div>
20+
);

‎packages/website/dummy-data/templates/package-home-replacement.tsx

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
import React from 'react';
2+
3+
export default ({
4+
pageComponent: Component,
5+
}: {
6+
data: Object;
7+
pageComponent: React.ElementType;
8+
}) => (
9+
<div
10+
style={{
11+
textAlign: 'center',
12+
color: 'rebeccapurple',
13+
backgroundColor: 'hotpink',
14+
borderRadius: '16px',
15+
padding: '8px',
16+
marginTop: '16px',
17+
}}
18+
>
19+
<Component />
20+
</div>
21+
);

‎packages/website/src/index.ts

+4
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ import {
33
buildPipeline,
44
startServerPipeline,
55
exportServerPipeline,
6+
buildPagesPipeline,
67
} from './pipeline';
78

89
// @ts-ignore
@@ -20,6 +21,9 @@ const runBinary = () => {
2021
case 'dev': {
2122
return devPipeline(options.config, nextOptions).catch(handleError);
2223
}
24+
case 'build-pages': {
25+
return buildPagesPipeline(options.config).catch(handleError);
26+
}
2327
case 'build': {
2428
return buildPipeline(options.config, nextOptions).catch(handleError);
2529
}

‎packages/website/src/pipeline/buildPagesPipeline.ts

+30
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
import scanMetadata from './stages/scan-metadata';
2+
import generateWebsiteInfo from './stages/generate-website-info';
3+
import generatePages from './stages/generate-pages';
4+
import allPaths from './getAllPaths';
5+
6+
const buildPipeline = async (configPath?: string) => {
7+
const { rootPath, wrappersPath, pagesPath, pkgRoot, config } = await allPaths(
8+
configPath,
9+
);
10+
11+
return scanMetadata({
12+
rootPath,
13+
packagePathPatterns: config.packagesPaths,
14+
customPackageFields: config.customPackageFields,
15+
docs: config.docs,
16+
})
17+
.then(projectData => generateWebsiteInfo(projectData))
18+
.then(websiteInfo =>
19+
generatePages({
20+
wrappersPath,
21+
pagesPath,
22+
packageRoot: pkgRoot,
23+
...websiteInfo,
24+
...config,
25+
}),
26+
)
27+
.then(() => console.log('pages built'));
28+
};
29+
30+
export default buildPipeline;

‎packages/website/src/pipeline/index.ts

+1
Original file line numberDiff line numberDiff line change
@@ -2,3 +2,4 @@ export { default as devPipeline } from './devPipeline';
22
export { default as buildPipeline } from './buildPipeline';
33
export { default as startServerPipeline } from './startServerPipeline';
44
export { default as exportServerPipeline } from './exportPipeline';
5+
export { default as buildPagesPipeline } from './buildPagesPipeline';

‎packages/website/src/pipeline/stages/common/configuration-options.ts

+4
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
import { TemplateSpecifier } from '../../../../types';
2+
13
export interface ProjectDocsConfig {
24
// absolute path to the docs in the filesystem
35
path: string;
@@ -21,6 +23,7 @@ export interface BriskConfiguration {
2123
links?: string[];
2224
readMeImgSrc?: string;
2325
packagesImgSrc?: string;
26+
templates: TemplateSpecifier[];
2427
}
2528

2629
// User supplied brisk config
@@ -48,4 +51,5 @@ export interface UserConfig {
4851
links?: string[];
4952
readMeImgSrc?: string;
5053
packagesImgSrc?: string;
54+
templates?: TemplateSpecifier[];
5155
}

‎packages/website/src/pipeline/stages/generate-pages/index.ts

+1
Original file line numberDiff line numberDiff line change
@@ -118,6 +118,7 @@ export default createStage(
118118
generatorConfig,
119119
// @ts-ignore
120120
meta,
121+
input.templates,
121122
);
122123
},
123124
);

‎packages/website/src/pipeline/stages/generate-pages/integration.test.ts

+1
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,7 @@ describe('Generate pages build stage integration', () => {
8787
packagesPaths: [],
8888
docs: [],
8989
siteName: '',
90+
templates: [],
9091
};
9192

9293
await generatePagesStage(input);

‎packages/website/src/pipeline/stages/generate-pages/page-writers.integration.test.js

+26-6
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,7 @@ describe('Page templates', () => {
3434
{},
3535
{ wrappersPath, pagesPath },
3636
{ title: 'My Package' },
37+
[],
3738
);
3839

3940
const output = getOutput('output.js');
@@ -44,9 +45,15 @@ describe('Page templates', () => {
4445
import Component from '../README.md';
4546
import Wrapper from '../wrappers/package-home';
4647
48+
49+
50+
const data = {\\"pagePath\\":\\"output.js\\",\\"pageTitle\\":\\"My Package\\"}
51+
4752
export default () => (
48-
<Wrapper data={{\\"pagePath\\":\\"output.js\\",\\"pageTitle\\":\\"My Package\\"}}>
49-
<Component />
53+
<Wrapper data={data}>
54+
55+
<Component />
56+
5057
</Wrapper>
5158
);"
5259
`);
@@ -59,6 +66,7 @@ export default () => (
5966
{},
6067
{ wrappersPath, pagesPath },
6168
{ title: 'My Package' },
69+
[],
6270
);
6371

6472
const output = getOutput('output.js');
@@ -91,9 +99,15 @@ export default () => (
9199
import Component from '../README.md';
92100
import Wrapper from '../wrappers/package-docs';
93101
102+
103+
104+
const data = {\\"pagePath\\":\\"output.js\\",\\"pageTitle\\":\\"My Doc\\"}
105+
94106
export default () => (
95-
<Wrapper data={{\\"pagePath\\":\\"output.js\\",\\"pageTitle\\":\\"My Doc\\"}}>
96-
<Component />
107+
<Wrapper data={data}>
108+
109+
<Component />
110+
97111
</Wrapper>
98112
);"
99113
`);
@@ -186,9 +200,15 @@ export default () => (
186200
import Component from '../README.md';
187201
import Wrapper from '../wrappers/project-docs';
188202
203+
204+
205+
const data = {\\"pagePath\\":\\"output.js\\",\\"pageTitle\\":\\"My Doc\\"}
206+
189207
export default () => (
190-
<Wrapper data={{\\"pagePath\\":\\"output.js\\",\\"pageTitle\\":\\"My Doc\\"}}>
191-
<Component />
208+
<Wrapper data={data}>
209+
210+
<Component />
211+
192212
</Wrapper>
193213
);"
194214
`);

0 commit comments

Comments
 (0)