Skip to content

Add URL rewrite for markdown docs#199

Open
shainaraskas wants to merge 1 commit into
elastic:masterfrom
shainaraskas:add-link-mappings
Open

Add URL rewrite for markdown docs#199
shainaraskas wants to merge 1 commit into
elastic:masterfrom
shainaraskas:add-link-mappings

Conversation

@shainaraskas
Copy link
Copy Markdown
Member

@shainaraskas shainaraskas commented May 22, 2026

Overview

Adds optional URL rewriting in the markdown renderer.

Consumers can declare (url, link, text) triples under render.linkMappings in the config file. The markdown renderer rewrites occurrences of the url in field and type doc comments to [text](link) at render time. Lets us produce docs-builder cross-repo links from plain URLs in godoc instead of post-processing the rendered markdown in a downstream script.

Replaces elastic/cloud-on-k8s#9454 - will follow up with mappings in cloud-on-k8s after this change is released

Changes

  • new render.linkMappings config field
  • RewriteLinks method on the markdown renderer
  • called automatically inside RenderFieldDoc; bundled markdown templates also call it on $type.Doc (which doesn't go through RenderFieldDoc)
  • empty/unset linkMappings is a no-op, so existing consumers see no behavior change

I've left the asciidoc renderer alone:

  • it would require a different set of mappings
  • the asciidoc build has less strict link validation
  • we are no longer actively contributing to those docs at Elastic (they're stable/don't require generation)

Questions

  • Should this be altered to consume a mapping file external to the config.yml?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant