From 85e28a59205c4b008f693a6ceb5821487a3fedfa Mon Sep 17 00:00:00 2001 From: Darius Cepulis Date: Fri, 24 Apr 2026 14:56:44 -0500 Subject: [PATCH] feat(packages): support cli:omit markers for llm-only doc content (#1466) --- packages/cli/src/commands/docs.ts | 6 +- packages/cli/src/commands/tests/docs.test.ts | 6 ++ packages/cli/src/utils/replace.ts | 5 ++ packages/cli/src/utils/tests/replace.test.ts | 56 ++++++++++++++++++- site/integrations/llms-markdown.ts | 9 +++ site/src/content/docs/how-to/installation.mdx | 11 ++-- 6 files changed, 85 insertions(+), 8 deletions(-) diff --git a/packages/cli/src/commands/docs.ts b/packages/cli/src/commands/docs.ts index ed49c0b6..f7d32ff4 100644 --- a/packages/cli/src/commands/docs.ts +++ b/packages/cli/src/commands/docs.ts @@ -6,7 +6,7 @@ import { getConfigValue } from '../utils/config.js'; import { docExistsInAnyFramework, readBundledDoc, readLlmsTxt } from '../utils/docs.js'; import { formatInstallationCode } from '../utils/format.js'; import { mapRawSkin, type PartialInstallFlags, promptFramework, promptInstallOptions } from '../utils/prompts.js'; -import { replaceMarker } from '../utils/replace.js'; +import { replaceMarker, stripOmitMarkers } from '../utils/replace.js'; interface ParsedFlags { framework?: string; @@ -178,7 +178,7 @@ export async function handleDocs(flags: ParsedFlags, positionals: string[]): Pro } const generated = formatInstallationCode(opts); - const output = replaceMarker(markdown, 'installation', generated); + const output = stripOmitMarkers(replaceMarker(markdown, 'installation', generated)); printVersionHeader(); console.log(output); return; @@ -186,5 +186,5 @@ export async function handleDocs(flags: ParsedFlags, positionals: string[]): Pro // Regular doc: print as-is printVersionHeader(); - console.log(markdown); + console.log(stripOmitMarkers(markdown)); } diff --git a/packages/cli/src/commands/tests/docs.test.ts b/packages/cli/src/commands/tests/docs.test.ts index 66fb7907..fe2492c2 100644 --- a/packages/cli/src/commands/tests/docs.test.ts +++ b/packages/cli/src/commands/tests/docs.test.ts @@ -6,6 +6,10 @@ const INSTALLATION_DOC = `# Installation Intro paragraph. + +Run the CLI to generate install code. + + Placeholder for CLI-generated code. @@ -205,6 +209,8 @@ describe('handleDocs', () => { expect(out).toContain('## HTML'); expect(out).toContain(''); expect(out).not.toContain('\\n[\\s\\S]*?\\n`); return markdown.replace(re, () => replacement); } + +export function stripOmitMarkers(markdown: string): string { + const re = /\n?\n[\s\S]*?\n\n?/g; + return markdown.replace(re, '\n'); +} diff --git a/packages/cli/src/utils/tests/replace.test.ts b/packages/cli/src/utils/tests/replace.test.ts index d69a2c0d..6e2cc979 100644 --- a/packages/cli/src/utils/tests/replace.test.ts +++ b/packages/cli/src/utils/tests/replace.test.ts @@ -1,5 +1,5 @@ import { describe, expect, it } from 'vitest'; -import { replaceMarker } from '../replace.js'; +import { replaceMarker, stripOmitMarkers } from '../replace.js'; describe('replaceMarker', () => { it('replaces content between markers', () => { @@ -63,3 +63,57 @@ end`; expect(result).toBe('start\nsingle line\nend'); }); }); + +describe('stripOmitMarkers', () => { + it('removes content between omit markers', () => { + const markdown = `# Title + + +CLI-only hint + + +## Footer`; + + const result = stripOmitMarkers(markdown); + expect(result).not.toContain('CLI-only hint'); + expect(result).not.toContain('cli:omit'); + expect(result).toContain('# Title'); + expect(result).toContain('## Footer'); + }); + + it('returns unchanged markdown when no markers are present', () => { + const markdown = '# Title\n\nSome content'; + expect(stripOmitMarkers(markdown)).toBe(markdown); + }); + + it('removes multiple omit blocks with different ids', () => { + const markdown = `before + +alpha + +middle + +beta + +after`; + + const result = stripOmitMarkers(markdown); + expect(result).not.toContain('alpha'); + expect(result).not.toContain('beta'); + expect(result).toContain('before'); + expect(result).toContain('middle'); + expect(result).toContain('after'); + }); + + it('handles multiline content inside an omit block', () => { + const markdown = `start + +line 1 +line 2 +line 3 + +end`; + + expect(stripOmitMarkers(markdown)).toBe('start\nend'); + }); +}); diff --git a/site/integrations/llms-markdown.ts b/site/integrations/llms-markdown.ts index 5d8f41c5..18a2a3fa 100644 --- a/site/integrations/llms-markdown.ts +++ b/site/integrations/llms-markdown.ts @@ -49,6 +49,15 @@ export default function llmsMarkdown(): AstroIntegration { }, }); + // Wrap [data-cli-omit] content with text markers the CLI strips from its output + turndown.addRule('cli-omit', { + filter: (node) => node.nodeType === 1 && (node as Element).getAttribute('data-cli-omit') !== null, + replacement: (content, node) => { + const id = (node as Element).getAttribute('data-cli-omit'); + return `\n\n${content}\n\n`; + }, + }); + // Track all docs and blog pages for llms.txt index const docsPages: PageEntry[] = []; const blogPages: PageEntry[] = []; diff --git a/site/src/content/docs/how-to/installation.mdx b/site/src/content/docs/how-to/installation.mdx index c733945f..de6ae7ce 100644 --- a/site/src/content/docs/how-to/installation.mdx +++ b/site/src/content/docs/how-to/installation.mdx @@ -32,9 +32,9 @@ Video.js is an **HTML video player built on custom elements** — lightweigh -
+
-Run `npx @videojs/cli docs how-to/installation` interactively, or pass all flags: +The code examples in this guide can be tailored to your use case. Run `npx @videojs/cli docs how-to/installation` interactively, or pass all flags: ```bash npx @videojs/cli docs how-to/installation \ @@ -45,7 +45,6 @@ npx @videojs/cli docs how-to/installation \ --source-url \ --install-method ``` -
@@ -81,6 +80,10 @@ Video.js supports a wide range of file types and hosting services. It's easy to + + +
+ ## Install Video.js @@ -142,7 +145,7 @@ Add it to your components folder in a new file. - +
## CSP