rushstack icon indicating copy to clipboard operation
rushstack copied to clipboard

[api-documenter] Add a setting to remove the "do not edit" comment from the generated markdown

Open niming175 opened this issue 7 months ago • 2 comments
trafficstars

Summary

在生产的md文档中,在每个文件的顶部都会有这么一句:

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

这个在使用docusaurus部署我的文档会有影响。 所以,我想去掉这个注释,我该如何做?

In the generated Markdown (.md) documents, there is a line at the top of each file:

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

This causes issues when deploying my documentation using Docusaurus. So, I want to remove this comment. How can I do that?

Repro steps

Expected result:

Actual result:

Details

Standard questions

Please answer these questions to help us investigate your issue more quickly:

Question Answer
@microsoft/api-documenter version? 7.26.3
Operating system? Linux
Documentation target? Markdown
Would you consider contributing a PR? No
TypeScript compiler version? 5.7.2
Node.js version (node -v)? 20.14.0

niming175 avatar Apr 02 '25 02:04 niming175

This is a good suggestion.

However, for Docusaurus specifically, the <!-- --> tag should not be a problem. Here is an example from our own docs which use Docusaurus:

websites/api.rushstack.io/docs/pages/api-documenter.iapidocumenterpluginmanifest.features.md

---
hide_title: true
custom_edit_url: null
pagination_prev: null
pagination_next: null
---
<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@microsoft/api-documenter](./api-documenter.md) &gt; [IApiDocumenterPluginManifest](./api-documenter.iapidocumenterpluginmanifest.md) &gt; [features](./api-documenter.iapidocumenterpluginmanifest.features.md)

## IApiDocumenterPluginManifest.features property

The list of features provided by this plugin.

**Signature:**

```typescript
features: IFeatureDefinition[];
```

The purpose of the comment is to prevent people from accidentally modifying these machine-generated files.

octogonz avatar Apr 02 '25 19:04 octogonz

Here's a design proposal: https://github.com/microsoft/rushstack/pull/5178

octogonz avatar Apr 02 '25 19:04 octogonz