Skip to content

Conversation

@leemthompo
Copy link
Contributor

@leemthompo leemthompo commented Nov 12, 2025

Uses https://github.com/elastic/request-converter

I've got a hacky Python script that automates adding multi-language code examples to docs pages.

  • Finds console code blocks in markdown files
  • Converts them to multiple languages (Python, JS, PHP, Ruby, curl) using es-request-converter CLI
  • Pulls everything into snippets files
  • Wraps results in tab-sets (handles incrementing outermost colons in directives to work with steppers etc.)
  • Handles annotations, localhost replacement, and formatting quirks
  • Works around two bugs found in the converter itself (fixed in meantime!)

I'll share and "document" the script itself as part of ON week summary.

@github-actions
Copy link

github-actions bot commented Nov 12, 2025

🔍 Preview links for changed docs

- Extract code examples into _snippets/index-basics/ directory
- Replace inline code blocks with include directives
- Generate snippet files
@leemthompo leemthompo changed the title [ON week] Add language client examples to get-started/quickstarts [ON week] Add language client examples to get-started/index-basics.md Nov 14, 2025
@leemthompo
Copy link
Contributor Author

leemthompo commented Nov 17, 2025

It's necessary to pull all the examples into separate snippets and include them, otherwise it balloons the source page enormously. However, I'm on the fence about whether the console blocks should also be snippetized.
I think the authoring experience becomes more opaque when those console blocks aren't on the page itself, and it makes it even harder for infrequent contributors to make even trivial typo fixes in code blocks. Food for thought.

The latest iteration of my script has a -- regenerate option which wipes all the language examples and reconverts remaining console blocks.

@leemthompo
Copy link
Contributor Author

Putting this up for review for anybody interested in the approach, all feedback is welcome :)

@leemthompo leemthompo marked this pull request as ready for review November 17, 2025 08:48
@leemthompo leemthompo requested review from a team as code owners November 17, 2025 08:48
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.

2 participants