From 5c766a9ee5df0f08a07a2817916273ef479e7b46 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 20 Apr 2026 13:27:55 +0000 Subject: [PATCH 1/2] fix(docs-theme): inject displayed_sidebar frontmatter into autogenerated changelog The autogenerated changelog.md is gitignored, so repos can't set `displayed_sidebar` frontmatter persistently. Without it, removing the changelog from the sidebar causes Docusaurus to stop rendering any sidebar on the changelog page. Inject `displayed_sidebar` (default: `docs`) into both the full and placeholder changelog frontmatter. The sidebar name is configurable via the new `changelogDisplayedSidebar` theme option for repos whose sidebar is named differently (e.g. apify-sdk-js uses `sidebar`). Refs https://github.com/apify/apify-docs/issues/2442 https://claude.ai/code/session_01UCp88PBi3QiKXaJVREEqcu --- apify-docs-theme/src/markdown.js | 13 +++++++++---- apify-docs-theme/src/theme.js | 18 ++++++++++++------ 2 files changed, 21 insertions(+), 10 deletions(-) diff --git a/apify-docs-theme/src/markdown.js b/apify-docs-theme/src/markdown.js index 9af65e34a1..aa34a6a400 100644 --- a/apify-docs-theme/src/markdown.js +++ b/apify-docs-theme/src/markdown.js @@ -102,13 +102,16 @@ const prettifyPRLinks = () => (tree) => { /** * Adds frontmatter to the markdown content. * @param {string} changelog The markdown content. - * @param {string} title The frontmatter title. + * @param {object} [opts] + * @param {string} [opts.title] The frontmatter title. + * @param {string} [opts.displayedSidebar] The sidebar to display on the changelog page. * @returns {string} The markdown content with frontmatter. */ -function addFrontmatter(changelog, title = 'Changelog') { +function addFrontmatter(changelog, { title = 'Changelog', displayedSidebar = 'docs' } = {}) { return `--- title: ${title} sidebar_label: ${title} +displayed_sidebar: ${displayedSidebar} toc_max_heading_level: 3 --- ${changelog}`; @@ -131,9 +134,11 @@ function escapeMDXCharacters(changelog) { /** * Updates the markdown content for better UX and compatibility with Docusaurus v3. * @param {string} changelog The markdown content. + * @param {object} [opts] + * @param {string} [opts.displayedSidebar] The sidebar to display on the changelog page. * @returns {string} The updated markdown content. */ -function updateChangelog(changelog) { +function updateChangelog(changelog, { displayedSidebar } = {}) { const pipeline = unified() .use(remarkParse) .use(removeGitCliffMarkers) @@ -143,7 +148,7 @@ function updateChangelog(changelog) { .use(remarkStringify); changelog = pipeline.processSync(changelog).toString(); - changelog = addFrontmatter(changelog); + changelog = addFrontmatter(changelog, { displayedSidebar }); changelog = escapeMDXCharacters(changelog); return changelog; } diff --git a/apify-docs-theme/src/theme.js b/apify-docs-theme/src/theme.js index a8fd4b9977..c10ca69a5f 100644 --- a/apify-docs-theme/src/theme.js +++ b/apify-docs-theme/src/theme.js @@ -25,7 +25,7 @@ function findPathInParentOrThrow(endPath) { return filePath; } -async function generateChangelogFromGitHubReleases(paths, repo) { +async function generateChangelogFromGitHubReleases(paths, repo, { displayedSidebar } = {}) { const response = await axios.get(`https://api.github.com/repos/${repo}/releases`); const releases = response.data; @@ -40,11 +40,11 @@ async function generateChangelogFromGitHubReleases(paths, repo) { }); paths.forEach((p) => { - fs.writeFileSync(path.join(p, 'changelog.md'), updateChangelog(markdown)); + fs.writeFileSync(path.join(p, 'changelog.md'), updateChangelog(markdown, { displayedSidebar })); }); } -function copyChangelogFromRoot(paths, hasDefaultChangelog) { +function copyChangelogFromRoot(paths, hasDefaultChangelog, { displayedSidebar } = {}) { const sourceChangelogPath = findPathInParentOrThrow('CHANGELOG.md'); for (const docsPath of paths) { @@ -57,7 +57,7 @@ function copyChangelogFromRoot(paths, hasDefaultChangelog) { } const changelog = fs.readFileSync(sourceChangelogPath, 'utf-8'); - fs.writeFileSync(targetChangelogPath, updateChangelog(changelog)); + fs.writeFileSync(targetChangelogPath, updateChangelog(changelog, { displayedSidebar })); } } @@ -87,6 +87,7 @@ function theme( ), ]; + const displayedSidebar = options.changelogDisplayedSidebar ?? 'docs'; const hasDefaultChangelog = new Map(); for (const p of pathsToCopyChangelog) { @@ -95,6 +96,7 @@ function theme( fs.writeFileSync(`${p}/changelog.md`, `--- title: Changelog sidebar_label: Changelog +displayed_sidebar: ${displayedSidebar} --- It seems that the changelog is not available. This either means that your Docusaurus setup is misconfigured, or that your GitHub repository contains no releases yet. @@ -103,9 +105,13 @@ This either means that your Docusaurus setup is misconfigured, or that your GitH } if (options.changelogFromRoot) { - copyChangelogFromRoot(pathsToCopyChangelog, hasDefaultChangelog); + copyChangelogFromRoot(pathsToCopyChangelog, hasDefaultChangelog, { displayedSidebar }); } else { - await generateChangelogFromGitHubReleases(pathsToCopyChangelog, `${context.siteConfig.organizationName}/${context.siteConfig.projectName}`); + await generateChangelogFromGitHubReleases( + pathsToCopyChangelog, + `${context.siteConfig.organizationName}/${context.siteConfig.projectName}`, + { displayedSidebar }, + ); } } catch (e) { console.warn(`Changelog page could not be initialized: ${e.message}`); From 4224a5eb485fbbf441b8b9a49c6eaf45993c35f2 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 20 Apr 2026 13:42:05 +0000 Subject: [PATCH 2/2] fix(docs-theme): make displayed_sidebar optional and omit when undefined Per review feedback, default `changelogDisplayedSidebar` to undefined instead of `docs`. When undefined, the `displayed_sidebar` field is omitted from the generated changelog frontmatter entirely, letting Docusaurus fall back to its normal sidebar resolution. https://claude.ai/code/session_01UCp88PBi3QiKXaJVREEqcu --- apify-docs-theme/src/markdown.js | 15 +++++++++------ apify-docs-theme/src/theme.js | 8 +++++--- 2 files changed, 14 insertions(+), 9 deletions(-) diff --git a/apify-docs-theme/src/markdown.js b/apify-docs-theme/src/markdown.js index aa34a6a400..430d477e8c 100644 --- a/apify-docs-theme/src/markdown.js +++ b/apify-docs-theme/src/markdown.js @@ -104,15 +104,18 @@ const prettifyPRLinks = () => (tree) => { * @param {string} changelog The markdown content. * @param {object} [opts] * @param {string} [opts.title] The frontmatter title. - * @param {string} [opts.displayedSidebar] The sidebar to display on the changelog page. + * @param {string} [opts.displayedSidebar] The sidebar to display on the changelog page. Omitted from frontmatter if undefined. * @returns {string} The markdown content with frontmatter. */ -function addFrontmatter(changelog, { title = 'Changelog', displayedSidebar = 'docs' } = {}) { +function addFrontmatter(changelog, { title = 'Changelog', displayedSidebar } = {}) { + const fields = [ + `title: ${title}`, + `sidebar_label: ${title}`, + ...(displayedSidebar !== undefined ? [`displayed_sidebar: ${displayedSidebar}`] : []), + `toc_max_heading_level: 3`, + ]; return `--- -title: ${title} -sidebar_label: ${title} -displayed_sidebar: ${displayedSidebar} -toc_max_heading_level: 3 +${fields.join('\n')} --- ${changelog}`; } diff --git a/apify-docs-theme/src/theme.js b/apify-docs-theme/src/theme.js index c10ca69a5f..a2f64054cb 100644 --- a/apify-docs-theme/src/theme.js +++ b/apify-docs-theme/src/theme.js @@ -87,7 +87,10 @@ function theme( ), ]; - const displayedSidebar = options.changelogDisplayedSidebar ?? 'docs'; + const { changelogDisplayedSidebar: displayedSidebar } = options; + const displayedSidebarLine = displayedSidebar !== undefined + ? `displayed_sidebar: ${displayedSidebar}\n` + : ''; const hasDefaultChangelog = new Map(); for (const p of pathsToCopyChangelog) { @@ -96,8 +99,7 @@ function theme( fs.writeFileSync(`${p}/changelog.md`, `--- title: Changelog sidebar_label: Changelog -displayed_sidebar: ${displayedSidebar} ---- +${displayedSidebarLine}--- It seems that the changelog is not available. This either means that your Docusaurus setup is misconfigured, or that your GitHub repository contains no releases yet. `);