elastic / elastic/docs-builder
[Feature Request]: working links inside code blocks
- Dominant language
- C#
- Stars
- 24
- Forks
- 44
- Avg merge
- 1d 7h
- Merged PRs (30d)
- 146
Description
### Prerequisites
- [x] I have searched existing issues to ensure this feature hasn't already been requested
- [x] I have tested using the latest version of docs-builder
### What problem are you trying to solve?
I'd like to be able to generate API reference docs for the JS client where a code snippet describing one type can link to any other types it references. Example:
```markdown
```typescript
interface Foo {
name: [FooName](./FooName.md)
}
```
In this example, the rendered output would look like normal TypeScript (below) except the word `FooName` would be clickable.
```typescript
interface Foo {
name: FooName
}
```
Ideally, the visual style of linked text should be slightly different from unlinked, so that it's clear it's clickable.
### Proposed Solution
Add an optional argument to code blocks, much like the `callouts=false` argument, to instruct the renderer to render links as actual `` tags. Something like `linkable=true`, perhaps.
### Examples and Research
In Asciidoc, this was possible with the `subs=+macros` directive on a code block:
```asciidoc
[source,ts,subs=+macros]
----
interface Foo {
name: <>
}
----
```
### Alternative Solutions
Using `<1>` type footnotes is a proposed alternative. However, a long code block with lots of references to other types (e.g. the type definition for a search request) would be nearly unreadable due to the number of footnote links inside the code example.
### Additional Context
_No response_
### How important is this feature to you?
Important
Contributor guide
Assessment
This issue has not been assessed yet.