add docs for FeedXSLTOptions

facebook · Aug 2, 2024 · 221e695 · 221e695
1 parent cbb91f9
commit 221e695
Show file tree

Hide file tree

Showing 3 changed files with 39 additions and 8 deletions.
diff --git a/packages/docusaurus-plugin-content-blog/src/plugin-content-blog.d.ts b/packages/docusaurus-plugin-content-blog/src/plugin-content-blog.d.ts
@@ -523,6 +523,14 @@ declare module '@docusaurus/plugin-content-blog' {
       onInlineAuthors: 'ignore' | 'log' | 'warn' | 'throw';
     };
 
+  export type UserFeedXSLTOptions =
+    | boolean
+    | null
+    | {
+        rss?: string | boolean | null;
+        atom?: string | boolean | null;
+      };
+
   /**
    * Feed options, as provided by user config. `type` accepts `all` as shortcut
    */
@@ -532,13 +540,7 @@ declare module '@docusaurus/plugin-content-blog' {
       /** Type of feed to be generated. Use `null` to disable generation. */
       type?: FeedOptions['type'] | 'all' | FeedType;
       /** User-provided XSLT config for feeds, un-normalized */
-      xslt?:
-        | boolean
-        | null
-        | {
-            rss?: string | boolean | null;
-            atom?: string | boolean | null;
-          };
+      xslt?: UserFeedXSLTOptions;
     }
   >;
   /**

diff --git a/website/docs/api/plugins/plugin-content-blog.mdx b/website/docs/api/plugins/plugin-content-blog.mdx
@@ -77,6 +77,7 @@ Accepted fields:
 | `feedOptions.title` | `string` | `siteConfig.title` | Title of the feed. |
 | `feedOptions.description` | `string` | <code>\`$\{siteConfig.title} Blog\`</code> | Description of the feed. |
 | `feedOptions.copyright` | `string` | `undefined` | Copyright message. |
+| `feedOptions.xslt` | <code>boolean \| [FeedXSLTOptions](#FeedXSLTOptions)</code> | `undefined` | Copyright message. |
 | `feedOptions.language` | `string` (See [documentation](http://www.w3.org/TR/REC-html40/struct/dirlang.html#langcodes) for possible values) | `undefined` | Language metadata of the feed. |
 | `sortPosts` | <code>'descending' \| 'ascending' </code> | `'descending'` | Governs the direction of blog post sorting. |
 | `processBlogPosts` | <code>[ProcessBlogPostsFn](#ProcessBlogPostsFn)</code> | `undefined` | An optional function which can be used to transform blog posts (filter, modify, delete, etc...). |
@@ -129,6 +130,25 @@ type ReadingTimeFn = (params: {
 type FeedType = 'rss' | 'atom' | 'json';
 ```
 
+#### `FeedXSLTOptions` {#FeedXSLTOptions}
+
+Permits to style the blog XML feeds so that browsers render them nicely with [XSLT](https://developer.mozilla.org/en-US/docs/Web/XSLT).
+
+- Use `true` to let the blog use its built-in `.xsl` and `.css` files to style the blog feed
+- Use a falsy value (`undefined | null | false`) to disable the feature
+- Use a `string` to provide a file path to a custom `.xsl` file relative to the blog content folder. By convention, you must provide a `.css` file with the exact same name.
+
+```ts
+type FeedXSLTOptions =
+  | boolean
+  | undefined
+  | null
+  | {
+      rss?: string | boolean | null | undefined;
+      atom?: string | boolean | null | undefined;
+    };
+```
+
 #### `CreateFeedItemsFn` {#CreateFeedItemsFn}
 
 ```ts

diff --git a/website/docs/blog.mdx b/website/docs/blog.mdx
@@ -602,9 +602,18 @@ type BlogOptions = {
     title?: string;
     description?: string;
     copyright: string;
+
     language?: string; // possible values: http://www.w3.org/TR/REC-html40/struct/dirlang.html#langcodes
     limit?: number | false | null; // defaults to 20
-    /** Allow control over the construction of BlogFeedItems */
+    // XSLT permits browsers to style and render nicely the feed XML files
+    xslt?:
+      | boolean
+      | {
+          //
+          rss?: string | boolean;
+          atom?: string | boolean;
+        };
+    // Allow control over the construction of BlogFeedItems
     createFeedItems?: (params: {
       blogPosts: BlogPost[];
       siteConfig: DocusaurusConfig;