Skip to content

feat(llms): convert ApiLink components to markdown links in generated .md files#339

Draft
viktorkombov wants to merge 4 commits into
vnextfrom
vkombov/convert-api-links-to-md-in-llms-md
Draft

feat(llms): convert ApiLink components to markdown links in generated .md files#339
viktorkombov wants to merge 4 commits into
vnextfrom
vkombov/convert-api-links-to-md-in-llms-md

Conversation

@viktorkombov

Copy link
Copy Markdown
Contributor

Closes #338

Improves the generated .md versions of documentation pages so they can be reliably parsed by LLMs and coding agents. First step of a broader effort to preserve all meaningful content from MDX source in the LLM-facing markdown output.

Previously <ApiLink> components were stripped entirely from .md files, losing all API identifiers and links. They are now resolved to proper markdown links using the same logic as the rendered HTML.

Changes

  • stripMdxForLlms converts <ApiLink …/> to [`IgxToast`](url) (or `IgxToast` fallback when index is unavailable) instead of removing them
  • platformContext option added to siteMetaIntegration / createDocsSite to supply the API index at build time
  • getPlatformContext() accepts an optional explicit platform name to avoid relying on env vars
  • Both docs/angular and docs/xplat pass platformContext to createDocsSite
  • igniteui-astro-components pointed to local repo (pending astro-components PR merge)

Verification

  • <ApiLink type="Grid" /> resolves to a working link in the generated .md
  • <ApiLink type="Grid" member="rowSelection" /> resolves with correct member anchor
  • <ApiLink kind="sass" module="themes" type="function-avatar-theme" /> resolves to correct Sass docs URL
  • <ApiLink label="custom" type="Toast" /> uses the label override, not the auto-generated name
  • <ApiLink prefixed={false} type="IgxToast" /> skips prefix prepending
  • API References section entries are links, not plain inline code
  • Unresolved symbols fall back to `TypeName` inline code (no broken links)
  • Angular, React, WebComponents, and Blazor builds all produce correct platform-specific URLs

Checklist:

  • check topic's TOC/menu and paragraph headings
  • Include TOC topic labels in the topic content when it has a valuable update, is new, or is considered preview / beta
  • link to other topics using ../relative/path.md
  • at the References section at the end of the topic add links to topics, samples, etc
  • reference API documentation instead of adding a section with API

  • use valid component names - [Data] Grid, IgxSelectComponent, <igx-combo>
  • use spell checker tool (VS Code, Grammarly, Microsoft Editor)
  • add inline code blocks for the names of classes / tags / properties
  • add language descriptor for the code blocks
  • check if links function by running the check-api/mdx npm commands
  • check if sample is working and fully visible in the topic
  • check if sample is working and fully visible in the StackBlitz
  • check if code blocks match the code in StackBlitz demo


  • do not resolve requested changes (leave that to the reviewer)

@viktorkombov viktorkombov added ❌ status: awaiting-test PRs awaiting manual verification 🛠️ status: in-development Issues and PRs with active development on them and removed ❌ status: awaiting-test PRs awaiting manual verification labels Jun 18, 2026
@viktorkombov viktorkombov marked this pull request as draft June 18, 2026 13:47
viktorkombov and others added 3 commits June 19, 2026 14:02
- Introduced a new module `html-to-md.ts` for converting built Astro HTML pages to Markdown.
- Integrated `turndown` and `turndown-plugin-gfm` for Markdown formatting.
- Updated `package.json` to include new dependencies for Markdown conversion.
- Modified `integration.ts` to utilize the new HTML to Markdown conversion, replacing the previous MDX stripping logic.
- Enhanced logging for Markdown generation process and added selector guard for code blocks.
Comment thread src/html-to-md.ts
Comment on lines +108 to +109
const rawCode = body
.replace(/<[^>]+>/g, '')
Comment thread src/html-to-md.ts
Comment on lines +108 to +110
const rawCode = body
.replace(/<[^>]+>/g, '')
.replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&amp;/g, '&')
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

🛠️ status: in-development Issues and PRs with active development on them

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Improve generated .md documentation for LLMs across all platforms

2 participants