♻️ use page to implement changelog sidebar instead

Author: StarHeartHunt

packages/plugin-changelog/src/index.ts

@@ -8,6 +8,7 @@ import {
   getChunkContent,
   getChunkFilename,
   getChunkTitle,
+  getPaginator,
 } from "./utils";
 
 import type {
@@ -16,12 +17,14 @@ import type {
   Plugin,
 } from "@docusaurus/types";
 import type { Options, PluginOptions } from "./options";
+import type { ChangelogChunk } from "./types";
 
 export const HEADER = `---
-sidebar_position: {{position}}
 {{extraHeader}}
 ---
 
+import DocPaginator from "@theme/DocPaginator"
+
 # {{chunkTitle}}
 `;
 
@@ -48,6 +51,35 @@ ${content}
   };
 }
 
+export async function getChangelogItems(
+  changelogPath: string,
+  changelogPerPage: number,
+): Promise<ChangelogChunk> {
+  const fileContent = await fs.readFile(changelogPath, "utf-8");
+  const sections = fileContent
+    .split(/(?=\n## )/)
+    .map(processSection)
+    .filter(Boolean);
+  const chunks = chunkArray(sections, changelogPerPage);
+
+  return chunks;
+}
+
+export function getChangelogItemsSync(
+  changelogPath: string,
+  changelogPerPage: number,
+): ChangelogChunk {
+  // eslint-disable-next-line no-restricted-properties
+  const fileContent = fs.readFileSync(changelogPath, "utf-8");
+  const sections = fileContent
+    .split(/(?=\n## )/)
+    .map(processSection)
+    .filter(Boolean);
+  const chunks = chunkArray(sections, changelogPerPage);
+
+  return chunks;
+}
+
 export default async function pluginChangelog(
   context: LoadContext,
   options: PluginOptions,
@@ -56,12 +88,10 @@ export default async function pluginChangelog(
   const generateDir = path.join(siteDir, options.changelogDestPath);
   const changelogPath = path.join(siteDir, options.changelogPath);
 
-  const fileContent = await fs.readFile(changelogPath, "utf-8");
-  const sections = fileContent
-    .split(/(?=\n## )/)
-    .map(processSection)
-    .filter(Boolean);
-  const chunks = chunkArray(sections, 10);
+  const chunks = await getChangelogItems(
+    changelogPath,
+    options.changelogPerPage,
+  );
   await Promise.all(
     chunks.map((chunk, index) =>
       fs.outputFile(
@@ -71,7 +101,7 @@ export default async function pluginChangelog(
           HEADER.replaceAll("{{extraHeader}}", options.changelogHeader)
             .replaceAll("{{position}}", index.toString())
             .replaceAll("{{chunkTitle}}", getChunkTitle(chunk)),
-        ),
+        ) + getPaginator(chunks, index - 1, index + 1),
       ),
     ),
   );
@@ -83,8 +113,9 @@ export default async function pluginChangelog(
 
 const pluginOptionsSchema = Joi.object<PluginOptions>({
   changelogPath: Joi.string().default("src/changelog/changelog.md"),
-  changelogDestPath: Joi.string().default("docs/changelog"),
+  changelogDestPath: Joi.string().default("src/pages/changelog"),
   changelogHeader: Joi.string().default(""),
+  changelogPerPage: Joi.number().default(10),
 });
 
 export function validateOptions({
@@ -94,4 +125,4 @@ export function validateOptions({
   return validate(pluginOptionsSchema, options);
 }
 
-export type { Options, PluginOptions };
+export type { ChangelogChunk, Options, PluginOptions };

packages/plugin-changelog/src/options.ts

@@ -2,6 +2,7 @@ export type PluginOptions = {
   changelogPath: string;
   changelogDestPath: string;
   changelogHeader: string;
+  changelogPerPage: number;
 };
 
 export type Options = Partial<PluginOptions>;

packages/plugin-changelog/src/types.ts

@@ -0,0 +1,2 @@
+export type Section = { title: string; content: string } | null;
+export type ChangelogChunk = Section[][];

packages/plugin-changelog/src/utils.ts

@@ -1,4 +1,4 @@
-type Section = { title: string; content: string } | null;
+import type { Section } from "./types";
 
 export function chunkArray<T>(array: Array<T>, size: number): Array<Array<T>> {
   const result = [];
@@ -9,6 +9,34 @@ export function chunkArray<T>(array: Array<T>, size: number): Array<Array<T>> {
   return result;
 }
 
+export function getPaginator(
+  chunks: Section[][],
+  prevIdx: number,
+  nextIdx: number,
+): string {
+  let content = '\n<DocPaginator className="not-prose"';
+  if (prevIdx >= 0 && prevIdx < chunks.length) {
+    const chunk = chunks?.[prevIdx]?.[0];
+    if (chunk) {
+      const title = prevIdx === 0 ? "" : encodeURIComponent(chunk.title);
+      content += ` previous={{ title: "${chunk.title}", permalink: "/changelog/${title}" }}`;
+    }
+  }
+
+  if (nextIdx >= 0 && nextIdx < chunks.length) {
+    const chunk = chunks?.[nextIdx]?.[0];
+    if (chunk) {
+      content += ` next={{ title: "${
+        chunk.title
+      }", permalink: "/changelog/${encodeURIComponent(chunk.title)}" }}`;
+    }
+  }
+
+  content += "/>";
+
+  return content;
+}
+
 export function getChunkContent(chunk: Section[], header: string): string {
   let finalContent = "";
   for (const section of chunk) {

website/docs/changelog/.gitignore

@@ -75,8 +75,10 @@ export default async function createConfigAsync() {
       [
         "@nullbot/docusaurus-plugin-changelog",
         {
-          changelogHeader: `sidebar_custom_props:
-  sidebar_id: examples`,
+          changelogHeader: `description: Changelog
+toc_max_heading_level: 2
+sidebar_custom_props:
+  sidebar_id: changelog`,
         } satisfies ChangelogOptions,
       ],
     ],
@@ -143,7 +145,7 @@ export default async function createConfigAsync() {
               },
               {
                 label: "Changelog",
-                to: "/docs/next/changelog",
+                to: "/changelog",
               },
             ],
           },

website/docusaurus.config.ts

@@ -1,5 +1,12 @@
+import path from "path";
+
+import { getChangelogItemsSync } from "@nullbot/docusaurus-plugin-changelog";
+
 import type { SidebarsConfig } from "@docusaurus/plugin-content-docs";
 
+const changelogPath = path.join(__dirname, "src/changelog/changelog.md");
+const changelogItems = getChangelogItemsSync(changelogPath, 10);
+
 const sidebars: SidebarsConfig = {
   // By default, Docusaurus generates a sidebar from the docs folder structure
   main: [
@@ -42,7 +49,16 @@ const sidebars: SidebarsConfig = {
     {
       type: "category",
       label: "Changelog",
-      items: [{ type: "autogenerated", dirName: "changelog" }],
+      collapsible: false,
+      items: changelogItems.map<{ type: "link"; label: string; href: string }>(
+        (chunk, index) => ({
+          type: "link",
+          label: chunk[0]!.title,
+          href: `/changelog/${
+            index > 0 ? encodeURIComponent(chunk[0]!.title) : ""
+          }`,
+        }),
+      ),
     },
   ],
 };