facebook / facebook/docusaurus
Ergonomic way to enhance ToC within Markdown: insert TOC slice, exclude headings
- Lenguaje dominante
- TypeScript
- Estrellas
- 66.2k
- Forks
- 10k
- Merge medio
- 1 d 3 h
- PR fusionados (30 d)
- 52
Descripción
### Have you read the Contributing Guidelines on issues?
- [X] I have read the [Contributing Guidelines on issues](https://github.com/facebook/docusaurus/blob/main/CONTRIBUTING.md#reporting-new-issues).
### Description
Docusaurus currently allows manually altering (and even outright replacing) the ToC in Docs, as per https://github.com/facebook/docusaurus/issues/3915#issuecomment-896193142, but this is not documented.
This issue is as much a question on whether this is something we can expect to rely on, as a request to document it if the answer is "yes".
### Has this been requested on Canny?
_No response_
### Motivation
This is useful for documentation that is generated from other sources (in this case, a `man` page): while the HTML can be injected, the ToC does not follow suit (and I wouldn't expect it to. Or is that preferable?).
### API design
Here is [a doc](//github.com/gbdev/rgbds-www/blob/84d09523d8a0b2be62d4ec4afdbb42edf31be068/docs/rgbds.5.md) which largely consists of externally-generated HTML, for which we additionally [generate the ToC via a script](//github.com/gbdev/rgbds-www/blob/84d09523d8a0b2be62d4ec4afdbb42edf31be068/maintainer/man_to_html.sh).
```mdx
# rgbds(5) — object file format documentation
import generated from '!!raw-loader!./rgbds.5.html';
export const toc = [
{
"value": "DESCRIPTION",
"id": "DESCRIPTION",
"level": 2,
},
{
"value": "FILE STRUCTURE",
"id": "FILE_STRUCTURE",
"level": 2,
},
{
"value": "Header",
"id": "Header",
"level": 3,
},
{
"value": "Source file info",
"id": "Source_file_info",
"level": 3,
},
{
"value": "Symbols",
"id": "Symbols",
"level": 3,
},
{
"value": "Sections",
"id": "Sections",
"level": 3,
},
{
"value": "Assertions",
"id": "Assertions",
"level": 3,
},
{
"value": "RPN EXPRESSIONS",
"id": "RPN_EXPRESSIONS",
"level": 3,
},
{
"value": "SEE ALSO",
"id": "SEE_ALSO",
"level": 2,
},
{
"value": "HISTORY",
"id": "HISTORY",
"level": 2,
},
];
```
### Have you tried building it?
If the existing behavior is to be accepted as official, then nothing needs to be built; otherwise, what replacement API is deemed better will need to be discussed first.
### Self-service
- [ ] I'd be willing to contribute this feature to Docusaurus myself.
Guía de contribución
Evaluación
Este issue todavía no se ha evaluado.