feat(plugin-rss): initial - copy from rspack-website

biome.json

@@ -3,6 +3,12 @@
   "organizeImports": {
     "enabled": true
   },
+  "vcs": {
+    "enabled": true,
+    "clientKind": "git",
+    "defaultBranch": "main",
+    "useIgnoreFile": true
+  },
   "javascript": {
     "formatter": {
       "quoteStyle": "single",

e2e/fixtures/plugin-rss/blog/index.md

@@ -0,0 +1,5 @@
+---
+date: 2024-01-01 08:00:00
+---
+
+# Rspress Best Practice

e2e/fixtures/plugin-rss/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@rspress-fixture/doc-plugin-rss",
+  "version": "1.0.0",
+  "private": true,
+  "scripts": {
+    "dev": "rspress dev",
+    "build": "rspress build",
+    "preview": "rspress preview"
+  },
+  "dependencies": {
+    "@rspress/plugin-rss": "workspace:*",
+    "rspress": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "^14"
+  }
+}

e2e/fixtures/plugin-rss/releases/index.md

@@ -0,0 +1,7 @@
+# Hello World
+
+```jsx
+export default function HelloWorld() {
+  return <div>Hello World</div>;
+}
+```

e2e/fixtures/plugin-rss/rspress.config.ts

@@ -0,0 +1,4 @@
+import path from 'path';
+import { defineConfig } from 'rspress/config';
+
+export default defineConfig({});

e2e/fixtures/plugin-rss/tsconfig.json

@@ -0,0 +1,6 @@
+{
+  "compilerOptions": {
+    "esModuleInterop": true,
+    "jsx": "react-jsx"
+  }
+}

packages/document/docs/en/plugin/official-plugins/_meta.json

@@ -6,5 +6,6 @@
   "typedoc",
   "preview",
   "playground",
+  "rss",
   "shiki"
 ]

packages/document/docs/en/plugin/official-plugins/overview.mdx

@@ -11,6 +11,7 @@ Official plugins include:
 - [@rspress/plugin-preview](./preview): Support preview of code blocks in Markdown/MDX.
 - [@rspress/plugin-playground](./playground): Provide a real-time playground to preview the code blocks in Markdown/MDX files.
 - [@rspress/plugin-shiki](./shiki): Integrates [Shiki](https://github.com/shikijs/shiki) for code syntax highlighting.
+- [@rspress/plugin-rss](./rss)：todo(xc2)
 
 ## Community Plugins
 

packages/document/docs/en/plugin/official-plugins/rss.mdx

@@ -0,0 +1,11 @@
+# @rspress/plugin-rss
+
+import { SourceCode, PackageManagerTabs } from 'rspress/theme';
+
+<SourceCode href="https://github.com/web-infra-dev/rspress/tree/main/packages/plugin-rss" />
+
+todo(xc2)
+
+## Installation
+
+<PackageManagerTabs command="add @rspress/plugin-rss -D" />

packages/document/docs/zh/plugin/official-plugins/_meta.json

@@ -6,5 +6,6 @@
   "typedoc",
   "preview",
   "playground",
+  "rss",
   "shiki"
 ]

packages/document/docs/zh/plugin/official-plugins/overview.mdx

@@ -11,6 +11,7 @@
 - [@rspress/plugin-preview](./preview)：支持代码块中的组件预览。
 - [@rspress/plugin-playground](./playground)：支持代码块中的组件预览，并提供实时 Playground。
 - [@rspress/plugin-shiki](./shiki)：集成 [Shiki](https://github.com/shikijs/shiki) 来进行代码高亮的插件。
+- [@rspress/plugin-rss](./rss)：todo(xc2)
 
 ## 社区插件
 

packages/document/docs/zh/plugin/official-plugins/rss.mdx

@@ -0,0 +1,11 @@
+# @rspress/plugin-rss
+
+import { SourceCode, PackageManagerTabs } from 'rspress/theme';
+
+<SourceCode href="https://github.com/web-infra-dev/rspress/tree/main/packages/plugin-rss" />
+
+todo(xc2)
+
+## Installation
+
+<PackageManagerTabs command="add @rspress/plugin-rss -D" />

packages/plugin-rss/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023-present Bytedance, Inc. and its affiliates.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

packages/plugin-rss/README.md

@@ -0,0 +1,5 @@
+# @rspress/plugin-rss
+
+> RSS plugin for rspress
+
+[Documentation](https://rspress.dev/plugin/official-plugins/rss)

packages/plugin-rss/modern.config.ts

@@ -0,0 +1,17 @@
+import { defineConfig, moduleTools } from '@modern-js/module-tools';
+// https://modernjs.dev/module-tools/en/api
+export default defineConfig({
+  buildConfig: [
+    {
+      buildType: 'bundle',
+      format: 'cjs',
+      sourceMap: true,
+      input: ['./src/index.ts'],
+      target: 'es2020',
+      dts: {
+        respectExternal: false,
+      },
+    },
+  ],
+  plugins: [moduleTools()],
+});

packages/plugin-rss/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@rspress/plugin-rss",
+  "version": "1.16.0",
+  "description": "A plugin for feed generation for rspress",
+  "bugs": "https://github.com/web-infra-dev/rspress/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/web-infra-dev/rspress",
+    "directory": "packages/plugin-rss"
+  },
+  "license": "MIT",
+  "jsnext:source": "./src/index.ts",
+  "types": "./dist/index.d.ts",
+  "main": "./dist/index.js",
+  "scripts": {
+    "dev": "modern build -w",
+    "build": "modern build",
+    "reset": "rimraf ./**/node_modules",
+    "lint": "modern lint",
+    "change": "modern change",
+    "bump": "modern bump",
+    "pre": "modern pre",
+    "change-status": "modern change-status",
+    "gen-release-note": "modern gen-release-note",
+    "release": "modern release",
+    "new": "modern new",
+    "test": "vitest run --passWithNoTests",
+    "upgrade": "modern upgrade"
+  },
+  "engines": {
+    "node": ">=14.17.6"
+  },
+  "dependencies": {
+    "feed": "^4.2.2"
+  },
+  "devDependencies": {
+    "@types/node": "^18.11.17",
+    "@types/react": "^18",
+    "@rspress/shared": "workspace:*",
+    "@rspress/runtime": "workspace:*",
+    "react": "^18",
+    "typescript": "^5"
+  },
+  "peerDependencies": {
+    "react": ">=17.0.0",
+    "@types/react": ">=17.0.0",
+    "@rspress/runtime": "^1.0.0"
+  },
+  "files": ["dist", "static"],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true,
+    "registry": "https://registry.npmjs.org/"
+  }
+}

packages/plugin-rss/src/exports.ts

@@ -0,0 +1,10 @@
+import NodePath from 'node:path';
+
+export const PluginName = '@rspress/plugin-rss';
+
+export const PluginComponents = {
+  FeedsAnnotations: NodePath.resolve(
+    __dirname,
+    '../static/FeedsAnnotations.tsx',
+  ),
+} as const;

packages/plugin-rss/src/index.ts

@@ -0,0 +1,4 @@
+export * from './plugin-rss';
+export * from './type';
+export * from './exports';
+export { addLinkFeeds, linkFeedsToPage } from './utils';

packages/plugin-rss/src/plugin-rss.ts

@@ -0,0 +1,106 @@
+import type { RspressPlugin } from '@rspress/shared';
+import { Feed } from 'feed';
+import { mkdir, writeFile } from 'node:fs/promises';
+import * as NodePath from 'node:path';
+import type { PageIndexInfoWithFeeds, PluginRssOption, RssItem } from './type';
+import {
+  addLinkFeeds,
+  linkFeedsToPage,
+  notNullish,
+  resolveUrl,
+  toArray,
+} from './utils';
+import { PluginComponents, PluginName } from './exports';
+
+/**
+ * annotations:
+ * - `frontmatter.linkFeed` and `frontmatter.linkFeeds`: for linking a rss url in a page that not included in any rss files.
+ */
+export function pluginRss({
+  routePublicPath,
+  toFeedItem,
+  outDir: _outDir,
+  rssPublicPath = '/rss/',
+  feedOptions,
+  feedOptionsByName,
+}: PluginRssOption): RspressPlugin {
+  /**
+   * workaround for retrieving data of pages in `afterBuild`
+   * TODO: get pageData list directly in `afterBuild`
+   **/
+  let _rssWorkaround: null | Record<string, RssItem | undefined> = null;
+
+  /** page info to rss item */
+  const getRssItem = (page: PageIndexInfoWithFeeds): undefined | RssItem => {
+    const item = toFeedItem(page);
+    if (!item) return;
+
+    const feeds = toArray(item.feeds, item.feed);
+    if (!feeds.length) return;
+
+    const { link: _link, ...rest } = item;
+
+    return { ...rest, feeds, link: resolveUrl(routePublicPath, _link) };
+  };
+
+  return {
+    name: PluginName,
+    globalUIComponents: Object.values(PluginComponents),
+    beforeBuild(_, isProd) {
+      if (isProd) {
+        _rssWorkaround = {};
+      } else {
+        // skip on dev build
+        _rssWorkaround = null;
+      }
+    },
+    extendPageData(pageData: PageIndexInfoWithFeeds) {
+      if (!_rssWorkaround) return;
+
+      // rspress run `extendPageData` twice for each page - we need one only
+      if (!Object.prototype.hasOwnProperty.call(_rssWorkaround, pageData.id)) {
+        _rssWorkaround[pageData.id] = getRssItem(pageData);
+      }
+      const rss = _rssWorkaround[pageData.id];
+      if (rss) {
+        addLinkFeeds(pageData, rss.feeds);
+      }
+      linkFeedsToPage(rssPublicPath, pageData);
+    },
+    async afterBuild(config) {
+      if (!_rssWorkaround) return;
+
+      const items = Object.values(_rssWorkaround).filter(notNullish);
+      const feeds: Record<string, Feed> = Object.create(null);
+
+      for (const { feeds: feedNames, ...item } of items) {
+        for (const name of feedNames) {
+          if (!feeds[name]) {
+            feeds[name] = new Feed({
+              id: name,
+              title: config.title!,
+              copyright: config.themeConfig?.footer?.message || '',
+              description: config.description,
+              ...feedOptions,
+              ...feedOptionsByName?.[name],
+            });
+          }
+          feeds[name].addItem(item);
+        }
+      }
+
+      const outDir = NodePath.resolve(
+        _outDir || `${config.outDir || 'doc_build'}/rss/`,
+      );
+      for (const [file, feed] of Object.entries(feeds)) {
+        await mkdir(outDir, { recursive: true });
+        await writeFile(
+          NodePath.resolve(outDir, `${file}.rss`),
+          // better compatible than atom1
+          feed.rss2(),
+        );
+      }
+      _rssWorkaround = null;
+    },
+  };
+}

packages/plugin-rss/src/type.ts

@@ -0,0 +1,57 @@
+import type { FeedOptions, Item } from 'feed';
+import type { PageIndexInfo } from '@rspress/shared';
+import type { PartialPartial } from './utils';
+
+export type PageFeedInfo = { href: string };
+
+export type PageIndexInfoWithFeeds = PageIndexInfo & { feeds?: PageFeedInfo[] };
+export type RssItem = Item & { feeds: string[] };
+
+export type UserFeedOptions = PartialPartial<
+  FeedOptions,
+  'title' | 'copyright' | 'id'
+>;
+
+export type UserFeedItem<K extends string = any> = Item &
+  (
+    | {
+        /** the feed that this page belongs to */
+        feed: K;
+        feeds?: never;
+      }
+    | {
+        feed?: never;
+        /** the feed list that this page belongs to */
+        feeds: K[];
+      }
+  );
+
+// todo(xc2): refactor user api before pr ready
+export interface PluginRssOption<K extends string = any> {
+  /**
+   * the url prefix of articles
+   */
+  routePublicPath: string;
+  /**
+   * to generate the feed item options from page info. return `false` to exclude a page.
+   */
+  toFeedItem: (page: PageIndexInfo) => false | UserFeedItem<K>;
+  /**
+   * output dir for rss file.
+   * @default `${config.outDir || 'doc_build'}/rss/`
+   */
+  outDir?: string;
+  /**
+   * the url prefix of rss files
+   * @default "/rss/"
+   */
+  rssPublicPath?: string;
+  /**
+   * `FeedOptions` of `feed` module
+   */
+  feedOptions?: UserFeedOptions;
+  /**
+   * `FeedOptions` of `feed` module by feed name
+   */
+  feedOptionsByName?: Partial<Record<K, UserFeedOptions>>;
+}