docs(blog): add client generator intro blog post by Marshevskyy · Pull Request #399 · Redocly/website

Marshevskyy · 2026-08-27T09:43:00Z

What/Why/How?

preview https://marketing-site--3aecf8.preview.redocly.app/blog/agent-friendly-sdks

Adds the "Open-source, agent-friendly SDKs and tooling from OpenAPI description" blog post announcing redocly generate-client — built as a React page (blog/agent-friendly-sdks.page.tsx) instead of markdown, since the post has custom visuals: an inline SVG hero diagram, a numbered quick-start section with highlighted code, a generators table, and a reviewer-style CTA card with the eclipse glow.

Supporting theme changes:

@theme/utils/blog-post.js — blog routes ending in .page.tsx load their frontmatter via Realm's react-frontmatter loader, so React posts appear in the blog index, category pages, and RSS feed like markdown posts.
@theme/plugin.js — publishes a new blog-recent-posts shared data (top 4 posts) attached to every post route.
@theme/components/Blog/RecentPosts.tsx + @theme/templates/BlogPost.tsx — the "Latest from our blog" section now excludes the currently open post (previously the newest post listed itself). The BlogPost template is localized from marketing-pages with that one behavioral change.
blog/metadata/blog-metadata.yaml — new categories: api-descriptions:openapi and api-lifecycle:sdks (existing api-specifications untouched).

Notes

The post is dated 2026-08-27 — bump publishedDate if publication slips.
CTA links point at expected docs slugs (/docs/cli/commands/generate-client, /docs/cli/guides/customize-client-generation) — verify they exist by publish time.
No card image on purpose: the featured-post card on /blog renders image under a semi-transparent gradient, and recent posts follow the no-image convention.

Testing

Verified with npx @redocly/cli preview (1350 pages, no build errors): post renders with author/date/categories, appears first on /blog and in feed.xml with correct categories, recent-posts section excludes the open post on both React and markdown posts, new category pages return 200, and the layout holds at mobile widths.

🤖 Generated with Claude Code

- Add /blog/agent-friendly-sdks as a React page with inline hero diagram and a reviewer-style CTA card - Support react-frontmatter for .page.tsx blog posts in the theme plugin - Add blog-recent-posts shared data (top 4) and a shared RecentPosts component that excludes the currently open post; localize the BlogPost template to use it - Add api-descriptions:openapi and api-lifecycle:sdks blog categories Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

…indenting The 0-indent lists markdownlint wants break Markdoc tag parsing in the project build, so keep the original indentation and skip the file like other markdoc-heavy pages.

redocly

marketing-site AI Review: 🟢 Completed

Redocly Agent has reviewed your changes and found 4 potential issue(s).

Note

Low Risk

This PR strictly adds static marketing content and a metadata update. It does not alter core application logic, production systems, or existing UI themes. The complex React-based modifications and theme changes described in the initial PR description were reverted during the review process, safely isolating the changes to a standard Markdown file.

Overview

Adds a new Markdown blog post announcing redocly generate-client, an open-source tool for generating agent-friendly SDKs from OpenAPI descriptions. To simplify the PR, the author reverted the initial custom React page implementation in favor of a standard Markdown file paired with an SVG hero diagram. Additionally, the PR updates blog-metadata.yaml to introduce a new sdks subcategory under the API lifecycle section and sets the publication date to August 31, 2026.

- Use root-relative docs links in the CTA - Revert to api-specifications:openapi category (api-descriptions to be handled in a separate PR) - Dim the lead paragraph and add space below it - Highlight the steps tagline with TextGradient and add spacing - Use the theme CodeBlock with copy control for all code samples

illiaRedoc

LGTM

illiaRedoc · 2026-08-27T12:22:03Z

+                  No account, no config required. Flags or a <code>redocly.yaml</code>{' '}
+                  <code>client</code> block, your choice.


mb can be rephrased to prevent code block following code block

Restructured: the post is plain markdown now, and every code block is separated by text.

tatomyr · 2026-08-27T15:26:17Z

+import React from 'react';
+import styled from 'styled-components';

-export default Page;


Why do we need to modify Page in theme? It looks a better option to either modify it in the marketing pages or to enhance a specific page with the RecentPosts component. What do you think?

I would move components related to Blog from marketing-pages lib to this repo, but I would do it in separate PR.
The problem is in the shared template itself, every markdown post renders through BlogPost, and whichever post is newest lists itself in "Latest from our blog". So enhancing a single page wouldn't cover it.

Update: reworked the PR to keep it minimal — the post is plain markdown now and all theme changes are reverted, so this file is untouched. The recent-posts fix comes in the separate PR together with moving the Blog components into this repo.

tatomyr · 2026-08-27T15:27:31Z

-      data: { content, frontmatter },
-    } = await context.cache.load(route.fsPath, 'markdown-frontmatter');
+    // React blog posts export `frontmatter`; markdown posts use YAML frontmatter
+    const isReactPage = /\.page\.tsx?$/.test(route.fsPath);


Using regext seems fragile to me.

Agreed, switched from the path regex to the route's own type: the Realm markdown plugin stamps its routes with metadata.type === 'markdown', so the loader choice now branches on that instead of the filename shape.

Update: this change is out of the PR entirely — the post is markdown now, so no react-frontmatter loading is needed.

tatomyr · 2026-08-27T15:30:26Z

+              <div>
+                <StepLabel>Run one command</StepLabel>
+                <StepHint>
+                  No account, no config required. Flags or a <code>redocly.yaml</code>{' '}


Actually, some kind of config is still requred (either flags or redocly.yaml are necessary for generating).

Reworded. Strictly, every option has a default (--output falls back to clientOutput / .client.ts), so the accurate claim is "no account, no config file" — the text now says that, with flags/redocly.yaml as optional customization.

tatomyr · 2026-08-27T15:36:12Z

+                    "import { configure, listMenuItems, getOrderById } from './client.js';",
+                    '',
+                    'configure({ auth: { bearer: token } }); // sent only where an operation requires it',
+                    '',
+                    'const menu  = await listMenuItems({ query: { limit: 10 } });',
+                    "const order = await getOrderById({ path: { orderId: 'ord_01khr…' } });",


Suggested change

"import { configure, listMenuItems, getOrderById } from './client.js';",

'',

'configure({ auth: { bearer: token } }); // sent only where an operation requires it',

'',

'const menu = await listMenuItems({ query: { limit: 10 } });',

"const order = await getOrderById({ path: { orderId: 'ord_01khr…' } });",

"import { client } from './client.js';",

'',

'client.configure({ auth: { bearer: token } }); // sent only where an operation requires it',

'',

'const menu = await client.listMenuItems({ query: { limit: 10 } });',

"const order = await client.getOrderById({ path: { orderId: 'ord_01khr…' } });",

It's easier to understand this way (you configure a client, then invoke something from that same client).

The sample shows what the generator actually emits: the TypeScript SDK exports each operation as a named function plus a module-level configure (see the use-generated-client guide). A client. object would misrepresent the default surface — instance style exists via createClient, but flat imports are the default DX.

tatomyr · 2026-08-27T15:39:55Z

+          <div className="frame">
+            <HeroDiagram />
+          </div>
+          <figcaption>


I'd ask @Redocly/designers to check the look -- having too many font sizes on the page looks a bit hectic.

If you want text "As agents become part of engineering...." to remain large, let's add separator or more spacing, that will make it easier to read

Resolved by converting the post to plain markdown — it uses the standard blog typography now, no custom sizes.

tatomyr · 2026-08-27T15:47:30Z

+            exhaustively tested, and already carrying Redocly's production traffic.
+          </p>
+
+          <CtaCard>


The selection looks really ugly. Could you apply user-select: none/text where appropriate to improve UX/UI? (In other places too, perhaps.)

Those custom elements are gone — the post is plain markdown now.

tatomyr · 2026-08-27T16:11:58Z

+          </p>
+
+          <p>
+            One caveat, stated plainly: the command is still experimental, flags and output may


One caveat, stated plainly:

This is how AI talks 😄. Could you shift the text a little bit towards human-like flavour?

Ola24 · 2026-08-28T13:36:01Z

I think it might be better to style "One description. One command. Every time your API changes." as a quote (with a left rule and more spacing) rather than large accent text.

Right now, it’s not clear if it’s a takeaway, transition, or heading, and quote style would make it easier to read as an aside.

maybe like this:

Or something like this:

Ola24 · 2026-08-28T13:51:46Z

I would also add a few fixes for hero banner:

make text "typed SDKs, a CLI, mocks, and docs. Built for agents, owned by you." a bit bigger, for now it hard to read;
remove "browser tree dots" from banner, it feel heavy against the card;
also text "One OpenAPI description, one command, and every consumer of your API gets a typed, dependency-free artifact that regenerates instead of drifting." reads as floating right now. Either moving it inside the banner or centring it would make it read as a caption for the banner
also the blue arrows look a little odd: they have a brighter blue shade, and they appear thicker than all the elements they connect, thinner lines in the page’s accent color would look better

Ola24 · 2026-08-28T14:05:18Z

AlbinaBlazhko17 · 2026-08-28T14:22:09Z

+            (normalized to 3.x before generation).
+          </p>
+
+          <h2>Skills first</h2>


I was reading this section with no context, as i didn't review the client generator PR and found, that i don't understand the concept of the skills, why we need them, what purpose each skill serves and what will be inside each skill. So, i think it is better to add similar sentence to:

The design ships as agent skills. Every generator carries its own design document, and ejecting a generator drops it into your repo as a skill (.claude/skills/-generator/) beside the authoring guide.

Because we introduced a new concept for users and only us know what it is. AI generated for me example and from it i understand what it is:

$ redocly eject-generator zod generators/zod/… # the generator source, now yours generators/AGENTS.md # pointer, managed between markers .claude/skills/client-generators/SKILL.md # HOW to write a generator (142 lines) .claude/skills/zod-generator/SKILL.md # WHY this one is built this way (54 lines)

Agreed, added a one-sentence definition of skills and the actual file layout eject produces.

Good point — added a one-sentence definition of skills and the actual file layout eject produces (verified against the eject-generator command docs).

Co-authored-by: Illia Adamchuk <illia.adamchuk@redocly.com>

…egex Realm's markdown plugin stamps its routes with metadata.type === 'markdown', so branch on that rather than matching the .page.tsx filename shape. Also skip any post whose frontmatter cannot be loaded.

- Rewrite the post as a standard markdown blog post; the diagram is an SVG image in the body - Revert all theme changes (BlogPost template, plugin shared data, frontmatter loader) — the recent-posts fix moves to a separate PR - Address review feedback: complete the openapi.yaml snippet so the TypeScript example compiles against it, explain agent skills with the eject file layout, style the tagline as a quote, reword the caveat, and refine the hero diagram (bigger subtitle, no window dots, thinner accent-colored arrows)

The mcp-server markdownlint exclusion belongs in its own PR.

Marshevskyy · 2026-08-31T12:25:23Z

Thanks for the design pass! Applied: the tagline is styled as a quote, the banner subtitle is bigger, the window dots are removed, and the arrows are thinner in the accent color. The caption under the banner is gone — the post was converted to plain markdown, so the diagram is a regular image in the body now.

Marshevskyy · 2026-08-31T12:25:24Z

Note for all reviewers: I reworked the PR to keep it minimal — the post is now a plain markdown blog post (3 files: the post, the diagram SVG, and 2 lines of category metadata). All theme/template changes are reverted; the recent-posts fix and moving the Blog components into this repo will come in a separate PR. The markdownlint failure is a pre-existing issue with docs/realm/customization/mcp-server/index.md on main, unrelated to this PR — it will be fixed separately.

Marshevskyy and others added 3 commits August 27, 2026 12:42

docs(realm): fix list indentation in MCP server page for markdownlint

8786652

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs(other): exclude mcp-server page from markdownlint instead of re-…

8790795

…indenting The 0-indent lists markdownlint wants break Markdoc tag parsing in the project build, so keep the original indentation and skip the file like other markdoc-heavy pages.

Marshevskyy marked this pull request as ready for review August 27, 2026 09:59

Marshevskyy requested a review from a team as a code owner August 27, 2026 09:59

redocly Bot reviewed Aug 27, 2026

View reviewed changes

Comment thread blog/agent-friendly-sdks.page.tsx Outdated

Comment thread blog/metadata/blog-metadata.yaml Outdated

illiaRedoc reviewed Aug 27, 2026

View reviewed changes

Comment thread blog/agent-friendly-sdks.page.tsx Outdated

Comment thread blog/agent-friendly-sdks.page.tsx Outdated

Comment thread blog/agent-friendly-sdks.page.tsx Outdated

Marshevskyy requested a review from illiaRedoc August 27, 2026 12:00

illiaRedoc approved these changes Aug 27, 2026

View reviewed changes

illiaRedoc requested a review from a team August 27, 2026 12:30

tatomyr reviewed Aug 27, 2026

View reviewed changes

AlbinaBlazhko17 reviewed Aug 28, 2026

View reviewed changes

Marshevskyy and others added 2 commits August 31, 2026 11:55

Update blog/agent-friendly-sdks.page.tsx

2444a4d

Co-authored-by: Illia Adamchuk <illia.adamchuk@redocly.com>

docs(blog): select frontmatter loader by route type instead of path r…

3d80b85

…egex Realm's markdown plugin stamps its routes with metadata.type === 'markdown', so branch on that rather than matching the .page.tsx filename shape. Also skip any post whose frontmatter cannot be loaded.

redocly Bot reviewed Aug 31, 2026

View reviewed changes

Comment thread blog/agent-friendly-sdks.page.tsx Outdated

Marshevskyy added 2 commits August 31, 2026 14:40

docs(blog): revert markdownlint workflow change

674d748

The mcp-server markdownlint exclusion belongs in its own PR.

redocly Bot reviewed Aug 31, 2026

View reviewed changes

Comment thread blog/agent-friendly-sdks.md Outdated

Marshevskyy requested review from AlbinaBlazhko17, Ola24 and tatomyr August 31, 2026 12:26

Marshevskyy added 2 commits August 31, 2026 16:10

Merge branch 'main' into docs/client-generator-intro-blog-post

7c5efe5

docs(blog): bump publishedDate to 2026-08-31

c88718a

		No account, no config required. Flags or a <code>redocly.yaml</code>{' '}
		<code>client</code> block, your choice.

Uh oh!

Conversation

Marshevskyy commented Aug 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What/Why/How?

Notes

Testing

Uh oh!

redocly Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

illiaRedoc left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Ola24 commented Aug 28, 2026

Uh oh!

Ola24 commented Aug 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Ola24 commented Aug 28, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Marshevskyy commented Aug 31, 2026

Uh oh!

Marshevskyy commented Aug 31, 2026

Uh oh!

Reviewers

Assignees

Marshevskyy commented Aug 27, 2026 •

edited

Loading

redocly Bot left a comment •

edited

Loading

Ola24 commented Aug 28, 2026 •

edited

Loading