diff --git a/.github/workflows/guidelines.md b/.github/workflows/guidelines.md
index f827acfe..db8bbf95 100644
--- a/.github/workflows/guidelines.md
+++ b/.github/workflows/guidelines.md
@@ -229,6 +229,9 @@ Multi-line callout (summary + body):
- Use ` ```text ` for terminal output that learners read but do not type (for example, expected command output or error messages).
- Use ` ```yaml ` for standalone YAML configuration fragments, ` ```markdown ` for Markdown syntax examples, and ` ```html ` or ` ```xml ` for markup.
- When showing an agentic workflow example that includes both frontmatter and prompt body, prefer a ` ```markdown ` block that shows the full Markdown+frontmatter file shape instead of isolating the frontmatter in a standalone ` ```yaml ` region.
+- When a fenced snippet represents the contents of a file, add the filename after the language token so the rendered snippet chrome can surface it (for example, ` ```markdown .github/workflows/daily-status.md ` or ` ```yaml .github/workflows/daily-status.lock.yml `).
+- Prefer the bare relative path form for filename metadata in workshop content. The renderer also supports keyed metadata such as `title=` or `file=`, but workshop pages should use the bare path consistently unless a page needs a more complex title.
+- Match the filename extension to the snippet language (`.md` for `markdown`, `.yml`/`.yaml` for `yaml`, and so on), and keep the same filename across a page while the learner is still editing that same file.
## Enterprise user preference in design decisions
diff --git a/scripts/build-docs.test.js b/scripts/build-docs.test.js
index adbe2f51..4c78a24e 100644
--- a/scripts/build-docs.test.js
+++ b/scripts/build-docs.test.js
@@ -26,6 +26,22 @@ function buildDocs() {
};
}
+function renderSnippet(markdown) {
+ return execFileSync(
+ process.execPath,
+ [
+ "-e",
+ `
+ const { marked } = require("marked");
+ const { setupBasePlugins } = require("./scripts/lib/marked-setup");
+ setupBasePlugins();
+ process.stdout.write(marked.parse(${JSON.stringify(markdown)}));
+ `,
+ ],
+ { cwd: repoDir, encoding: "utf8" }
+ );
+}
+
test("workshop SPA renders a single document h1", () => {
const { html } = buildDocs();
@@ -125,6 +141,21 @@ test("markdown, md, yaml, and yml code blocks use compact icon-only editor chrom
assert.ok(css.includes("padding: 12px;"), "expected compact YAML code padding");
});
+test("code blocks wrap long lines without relying on mobile-only styles", () => {
+ const { css } = buildDocs();
+
+ assert.ok(css.includes(".markdown-body pre {\n position: relative;\n white-space: pre-wrap;\n overflow-wrap: anywhere;\n}"));
+ assert.ok(css.includes(".markdown-body pre > code {\n font-size: 1em;\n white-space: inherit;\n}"));
+});
+
+test("code block headers can render filenames from fence metadata", () => {
+ const html = renderSnippet("```yaml .github/workflows/hello.yml\nname: Hello\n```\n\n```markdown title=\"README.md\"\n# Hello\n```");
+
+ assert.ok(html.includes('.github/workflows/hello.yml'));
+ assert.ok(html.includes('README.md'));
+ assert.ok(html.includes(''));
+});
+
test("rendered workshop images use GitHub-like rounded corners", () => {
const { css } = buildDocs();
diff --git a/scripts/lib/docs.css b/scripts/lib/docs.css
index 986280ec..faca862c 100644
--- a/scripts/lib/docs.css
+++ b/scripts/lib/docs.css
@@ -605,9 +605,12 @@ html[data-color-mode="dark"] .workshop-nav-btn-secondary:focus-visible {
/* Code block copy button */
.markdown-body pre {
position: relative;
+ white-space: pre-wrap;
+ overflow-wrap: anywhere;
}
.markdown-body pre > code {
font-size: 1em;
+ white-space: inherit;
}
.code-copy-btn {
position: absolute;
@@ -671,6 +674,7 @@ html[data-color-mode="dark"] .code-copy-btn:hover {
display: flex;
align-items: center;
gap: 6px;
+ min-width: 0;
padding: 8px 14px;
background-color: #161b22;
border-bottom: 1px solid #30363d;
@@ -694,6 +698,20 @@ html[data-color-mode="dark"] .code-copy-btn:hover {
font-family: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace;
}
+.code-block-filename {
+ min-width: 0;
+ margin-left: auto;
+ overflow: hidden;
+ font-size: 11px;
+ text-overflow: ellipsis;
+ white-space: nowrap;
+}
+
+.terminal-bar .code-block-filename {
+ color: #8b949e;
+ font-family: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace;
+}
+
.markdown-body .terminal-pre {
margin: 0;
padding: 16px;
@@ -736,6 +754,7 @@ html[data-color-mode="dark"] .code-copy-btn:hover {
display: flex;
align-items: center;
gap: 8px;
+ min-width: 0;
padding: 8px 14px;
background: linear-gradient(90deg, #271052, #3b1b6f);
border-bottom: 1px solid #8957e5;
@@ -761,6 +780,10 @@ html[data-color-mode="dark"] .code-copy-btn:hover {
letter-spacing: 0.02em;
}
+.agent-prompt-bar .code-block-filename {
+ color: #c6a7ff;
+}
+
.markdown-body .agent-prompt-pre {
margin: 0;
padding: 16px 16px 16px 20px;
@@ -976,6 +999,7 @@ html[data-color-mode="dark"] .markdown-body li.task-list-item:not(.is-static).is
display: flex;
align-items: center;
gap: 8px;
+ min-width: 0;
padding: 8px 14px;
background-color: var(--bgColor-muted, #f6f8fa);
border-bottom: 1px solid var(--borderColor-muted, #d0d7de);
@@ -988,6 +1012,10 @@ html[data-color-mode="dark"] .markdown-body li.task-list-item:not(.is-static).is
line-height: 1;
}
+.markdown-editor-bar .code-block-filename {
+ color: var(--fgColor-muted, #59636e);
+}
+
.markdown-body .markdown-editor-pre {
margin: 0;
padding: 12px 12px 12px 16px;
@@ -1029,6 +1057,9 @@ html[data-color-mode="dark"] .markdown-body li.task-list-item:not(.is-static).is
html[data-color-mode="auto"] .markdown-editor-icon {
color: #8b949e;
}
+ html[data-color-mode="auto"] .markdown-editor-bar .code-block-filename {
+ color: #8b949e;
+ }
html[data-color-mode="auto"] .markdown-body .markdown-editor-pre {
background-color: #0d1117;
box-shadow: inset 3px 0 #30363d;
@@ -1057,6 +1088,9 @@ html[data-color-mode="dark"] .markdown-editor-bar {
html[data-color-mode="dark"] .markdown-editor-icon {
color: #8b949e;
}
+html[data-color-mode="dark"] .markdown-editor-bar .code-block-filename {
+ color: #8b949e;
+}
html[data-color-mode="dark"] .markdown-body .markdown-editor-pre {
background-color: #0d1117;
box-shadow: inset 3px 0 #30363d;
@@ -1086,6 +1120,7 @@ html[data-color-mode="dark"] .markdown-editor-block .code-copy-btn:hover {
display: flex;
align-items: center;
gap: 8px;
+ min-width: 0;
padding: 8px 14px;
background-color: var(--bgColor-muted, #f6f8fa);
border-bottom: 1px solid var(--borderColor-muted, #d0d7de);
@@ -1098,6 +1133,10 @@ html[data-color-mode="dark"] .markdown-editor-block .code-copy-btn:hover {
line-height: 1;
}
+.yaml-editor-bar .code-block-filename {
+ color: var(--fgColor-muted, #59636e);
+}
+
.markdown-body .yaml-editor-pre {
margin: 0;
padding: 12px;
@@ -1137,6 +1176,9 @@ html[data-color-mode="dark"] .markdown-editor-block .code-copy-btn:hover {
html[data-color-mode="auto"] .yaml-editor-icon {
color: #8b949e;
}
+ html[data-color-mode="auto"] .yaml-editor-bar .code-block-filename {
+ color: #8b949e;
+ }
html[data-color-mode="auto"] .markdown-body .yaml-editor-pre {
background-color: #0d1117;
}
@@ -1164,6 +1206,9 @@ html[data-color-mode="dark"] .yaml-editor-bar {
html[data-color-mode="dark"] .yaml-editor-icon {
color: #8b949e;
}
+html[data-color-mode="dark"] .yaml-editor-bar .code-block-filename {
+ color: #8b949e;
+}
html[data-color-mode="dark"] .markdown-body .yaml-editor-pre {
background-color: #0d1117;
}
diff --git a/scripts/lib/marked-setup.js b/scripts/lib/marked-setup.js
index f400d951..7bfcf292 100644
--- a/scripts/lib/marked-setup.js
+++ b/scripts/lib/marked-setup.js
@@ -19,6 +19,34 @@ const slugger = new GithubSlugger();
const shellLangs = new Set(['bash', 'sh', 'shell', 'zsh']);
const terminalOutputLangs = new Set(['console', 'output', 'plaintext', 'text']);
+function extractCodeBlockFilename(meta = '') {
+ let normalizedMeta = meta.trim();
+ if (!normalizedMeta) return '';
+
+ if (normalizedMeta.startsWith('{') && normalizedMeta.endsWith('}')) {
+ normalizedMeta = normalizedMeta.slice(1, -1).trim();
+ }
+
+ const keyedFilenameMatch = normalizedMeta.match(
+ /(?:^|\s)(?:file|filename|path|title)=(?:"([^"]+)"|'([^']+)'|(\S+))/
+ );
+ if (keyedFilenameMatch) {
+ return keyedFilenameMatch[1] || keyedFilenameMatch[2] || keyedFilenameMatch[3] || '';
+ }
+
+ return /\s|=/.test(normalizedMeta) ? '' : normalizedMeta;
+}
+
+function parseCodeBlockInfo(lang = '') {
+ const info = lang.trim();
+ const firstTokenMatch = info.match(/^\S*/);
+ const langKey = (firstTokenMatch?.[0] || '').toLowerCase();
+ const meta = info.slice(firstTokenMatch?.[0]?.length || 0).trim();
+ const filename = extractCodeBlockFilename(meta);
+
+ return { langKey, filename };
+}
+
// Register the heading anchor, task-list item, alert, syntax-highlight, and
// code-block renderer plugins. Call this once before processing any markdown.
function setupBasePlugins() {
@@ -91,22 +119,26 @@ function setupBasePlugins() {
useNewRenderer: true,
renderer: {
code({ text, lang, escaped }) {
- const langKey = (lang || '').match(/^\S*/)?.[0]?.toLowerCase() ?? '';
+ const { langKey, filename } = parseCodeBlockInfo(lang || '');
const codeText = text.replace(/\n$/, '') + '\n';
const codeHtml = escaped ? codeText : escapeHtml(codeText);
+ const filenameHtml = filename
+ ? `${escapeHtml(filename)}`
+ : '';
if (langKey === 'prompt') {
- return `\n
✦Agent prompt
\n
${codeHtml}
\n
\n
✦Agent prompt${filenameHtml}
\n
${codeHtml}
\n
\n
◇${filenameHtml}
\n
${codeHtml}
\n
\n
≡${filenameHtml}
\n
${codeHtml}
\n
\n
${terminalLabel}
\n
${codeHtml}
\n
\n
${terminalLabel}${filenameHtml}
\n
${codeHtml}
\n