Skip to content

Commit 7f34fa3

Browse files
octogonzoctogonz
committed
Implement MarkdownDocumenterFeature.onBeforeWritePage() event
1 parent f38f825 commit 7f34fa3

File tree

8 files changed

+68
-14
lines changed

8 files changed

+68
-14
lines changed

‎apps/api-documenter/src/cli/GenerateAction.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,7 @@ export class GenerateAction extends BaseAction {
4646
const apiModel: ApiModel = this.buildApiModel();
4747

4848
if (configFile.outputTarget === 'markdown') {
49-
const markdownDocumenter: MarkdownDocumenter = new MarkdownDocumenter(apiModel);
49+
const markdownDocumenter: MarkdownDocumenter = new MarkdownDocumenter(apiModel, pluginLoader);
5050
markdownDocumenter.generateFiles(this.outputFolder);
5151
} else {
5252
const yamlDocumenter: ExperimentalYamlDocumenter = new ExperimentalYamlDocumenter(apiModel, configFile);

‎apps/api-documenter/src/cli/MarkdownAction.ts‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ import { ApiDocumenterCommandLine } from './ApiDocumenterCommandLine';
55
import { BaseAction } from './BaseAction';
66
import { MarkdownDocumenter } from '../documenters/MarkdownDocumenter';
77
import { ApiModel } from '@microsoft/api-extractor-model';
8+
import { PluginLoader } from '../plugin/PluginLoader';
89

910
export class MarkdownAction extends BaseAction {
1011
constructor(parser: ApiDocumenterCommandLine) {
@@ -18,7 +19,9 @@ export class MarkdownAction extends BaseAction {
1819

1920
protected onExecute(): Promise<void> { // override
2021
const apiModel: ApiModel = this.buildApiModel();
21-
const markdownDocumenter: MarkdownDocumenter = new MarkdownDocumenter(apiModel);
22+
23+
const pluginLoader: PluginLoader = new PluginLoader();
24+
const markdownDocumenter: MarkdownDocumenter = new MarkdownDocumenter(apiModel, pluginLoader);
2225
markdownDocumenter.generateFiles(this.outputFolder);
2326
return Promise.resolve();
2427
}

‎apps/api-documenter/src/documenters/MarkdownDocumenter.ts‎

Lines changed: 19 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -51,19 +51,23 @@ import { DocTableCell } from '../nodes/DocTableCell';
5151
import { DocNoteBox } from '../nodes/DocNoteBox';
5252
import { Utilities } from '../utils/Utilities';
5353
import { CustomMarkdownEmitter } from '../markdown/CustomMarkdownEmitter';
54+
import { PluginLoader } from '../plugin/PluginLoader';
55+
import { IMarkdownDocumenterFeatureOnBeforeWritePageArgs } from '../plugin/MarkdownDocumenterFeature';
5456

5557
/**
5658
* Renders API documentation in the Markdown file format.
5759
* For more info: https://en.wikipedia.org/wiki/Markdown
5860
*/
5961
export class MarkdownDocumenter {
6062
private readonly _apiModel: ApiModel;
63+
private readonly _pluginLoader: PluginLoader;
6164
private readonly _tsdocConfiguration: TSDocConfiguration;
6265
private readonly _markdownEmitter: CustomMarkdownEmitter;
6366
private _outputFolder: string;
6467

65-
public constructor(apiModel: ApiModel) {
68+
public constructor(apiModel: ApiModel, pluginLoader: PluginLoader) {
6669
this._apiModel = apiModel;
70+
this._pluginLoader = pluginLoader;
6771
this._tsdocConfiguration = CustomDocNodes.configuration;
6872
this._markdownEmitter = new CustomMarkdownEmitter(this._apiModel);
6973
}
@@ -249,7 +253,20 @@ export class MarkdownDocumenter {
249253
}
250254
});
251255

252-
FileSystem.writeFile(filename, stringBuilder.toString(), {
256+
let pageContent: string = stringBuilder.toString();
257+
258+
if (this._pluginLoader.markdownDocumenterFeature) {
259+
// Allow the plugin to customize the pageContent
260+
const eventArgs: IMarkdownDocumenterFeatureOnBeforeWritePageArgs = {
261+
apiItem: apiItem,
262+
outputFilename: filename,
263+
pageContent: pageContent
264+
};
265+
this._pluginLoader.markdownDocumenterFeature.onBeforeWritePage(eventArgs);
266+
pageContent = eventArgs.pageContent;
267+
}
268+
269+
FileSystem.writeFile(filename, pageContent, {
253270
convertLineEndings: NewlineKind.CrLf
254271
});
255272
}

‎apps/api-documenter/src/index.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ export {
77
} from './plugin/IApiDocumenterPluginManifest';
88
export {
99
MarkdownDocumenterFeatureContext,
10-
IMarkdownDocumenterFeatureOnBeforeWritePage,
10+
IMarkdownDocumenterFeatureOnBeforeWritePageArgs,
1111
MarkdownDocumenterFeature
1212
} from './plugin/MarkdownDocumenterFeature';
1313
export {

‎apps/api-documenter/src/plugin/MarkdownDocumenterFeature.ts‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -17,11 +17,11 @@ export class MarkdownDocumenterFeatureContext {
1717
* Event arguments for MarkdownDocumenterFeature.onBeforeWritePage()
1818
* @public
1919
*/
20-
export interface IMarkdownDocumenterFeatureOnBeforeWritePage {
20+
export interface IMarkdownDocumenterFeatureOnBeforeWritePageArgs {
2121
/**
2222
* The API item corresponding to this page.
2323
*/
24-
apiItem: ApiItem;
24+
readonly apiItem: ApiItem;
2525

2626
/**
2727
* The page content. The onBeforeWritePage() handler can reassign this string to customize the page appearance.
@@ -31,7 +31,7 @@ export interface IMarkdownDocumenterFeatureOnBeforeWritePage {
3131
/**
3232
* The filename where the output will be written.
3333
*/
34-
outputFilename: string;
34+
readonly outputFilename: string;
3535
}
3636

3737
/**
@@ -47,7 +47,7 @@ export class MarkdownDocumenterFeature extends PluginFeature {
4747
* This event function is called before writing a page.
4848
* @virtual
4949
*/
50-
public onBeforeWritePage(eventArgs: IMarkdownDocumenterFeatureOnBeforeWritePage): void {
50+
public onBeforeWritePage(eventArgs: IMarkdownDocumenterFeatureOnBeforeWritePageArgs): void {
5151
// (implemented by child class)
5252
}
5353
}

‎common/reviews/api/api-documenter.api.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -22,9 +22,9 @@ export interface IFeatureDefinition {
2222
}
2323

2424
// @public
25-
export interface IMarkdownDocumenterFeatureOnBeforeWritePage {
26-
apiItem: ApiItem;
27-
outputFilename: string;
25+
export interface IMarkdownDocumenterFeatureOnBeforeWritePageArgs {
26+
readonly apiItem: ApiItem;
27+
readonly outputFilename: string;
2828
pageContent: string;
2929
}
3030

@@ -33,7 +33,7 @@ export class MarkdownDocumenterFeature extends PluginFeature {
3333
// (undocumented)
3434
context: MarkdownDocumenterFeatureContext;
3535
// @virtual
36-
onBeforeWritePage(eventArgs: IMarkdownDocumenterFeatureOnBeforeWritePage): void;
36+
onBeforeWritePage(eventArgs: IMarkdownDocumenterFeatureOnBeforeWritePageArgs): void;
3737
}
3838

3939
// @public

‎repo-scripts/doc-plugin-rush-stack/.vscode/launch.json‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
{
2+
// Use IntelliSense to learn about possible attributes.
3+
// Hover to view descriptions of existing attributes.
4+
// For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
5+
"version": "0.2.0",
6+
"configurations": [
7+
{
8+
"type": "node",
9+
"request": "launch",
10+
"name": "Launch Program",
11+
"program": "${workspaceFolder}/node_modules/@microsoft/api-documenter/lib/start.js",
12+
"cwd": "${workspaceFolder}/../generate-api-docs",
13+
"args": [
14+
"generate",
15+
"--input-folder",
16+
"../../common/temp/api",
17+
"--output-folder",
18+
"./dist"
19+
]
20+
},
21+
]
22+
}

‎repo-scripts/doc-plugin-rush-stack/src/RushStackFeature.ts‎

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,22 @@
11
// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
22
// See LICENSE in the project root for license information.
33

4-
import { MarkdownDocumenterFeature } from '@microsoft/api-documenter';
4+
import { MarkdownDocumenterFeature, IMarkdownDocumenterFeatureOnBeforeWritePageArgs } from '@microsoft/api-documenter';
55

66
export class RushStackFeature extends MarkdownDocumenterFeature {
77
public onInitialized(): void {
88
console.log('RushStackFeature: onInitialized()');
99
}
10+
11+
public onBeforeWritePage(eventArgs: IMarkdownDocumenterFeatureOnBeforeWritePageArgs): void {
12+
const header: string = [
13+
'---',
14+
'layout: page',
15+
'navigation_source: api_nav',
16+
'improve_this_button: false',
17+
'---',
18+
''
19+
].join('\n');
20+
eventArgs.pageContent = header + eventArgs.pageContent;
21+
}
1022
}

0 commit comments

Comments
 (0)