Skip to content

[Feature Request]: working links inside code blocks #1321

Open
@JoshMock

Description

@JoshMock

Prerequisites

  • I have searched existing issues to ensure this feature hasn't already been requested
  • 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:

```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.

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 <a> tags. Something like linkable=true, perhaps.

Examples and Research

In Asciidoc, this was possible with the subs=+macros directive on a code block:

[source,ts,subs=+macros]
----
interface Foo {
  name: <<FooName>>
}
----

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

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions