Skip to main content

Add documentation

Now that we have completed the code, it's time to add the documentation for your route. Open the appropriate file in the document (/website/docs), which in this example is website/docs/routes/programming.mdx.

In order to preview the documentation in real-time, you need to install the dependencies for the documentation. Run the following command in the website directory:

pnpm i

You can now preview the documentation in real-time by running the following command in the website directory:

pnpm run start
warning

You cannot switch to other languages in development mode. This is a technical limitation from Docusaurus.

The documentation is written in MDX v3 and rendered with Docusaurus v3.

To add documentation to your route, use the Route React component. It works like HTML tag. The following are the most commonly used component properties:

  • author: The route maintainer(s), separated by a single space. It should be the same as maintainer.js
  • example: The route example, with a leading /
  • path: The route path, which should be the same as the key in maintainer.js with the namespace. In the above example, it is /github/issue/:user/:repo?
  • paramsDesc: The route parameter description, in an array of strings that support Markdown.
  • The description must follow the order in which they appear in the path.
  • The number of description should match with the number of parameters in path. If you miss a description, the build will fail.
  • Route parameters ending with ?, * or + will be automatically marked as optional, zero or more or one or more, respectively.
  • Route parameters without a suffix are marked as required
  • There's no need to explicitly mention the necessity of path parameters again.
  • If a parameter is optional, make sure to mention the default value.

Documentation examples​

Repo Issues (No parameter)​

<Route author="HenryQW" example="/sspai/series" path="/sspai/series" />

πŸ‘¨β€πŸ’» Author: @HenryQW

πŸ’‘ Example: https://rsshub.mlj-dragon.cn/sspai/series

🚏 Route: /sspai/series

Parameters: N/A

Repo Issues (Multiple parameters)​

<Route author="HenryQW" example="/github/issue/DIYgod/RSSHub" path="/github/issue/:user/:repo?" paramsDesc={['GitHub username', 'GitHub repo name, `RSSHub` by default']} />

πŸ‘¨β€πŸ’» Author: @HenryQW

πŸ’‘ Example: https://rsshub.mlj-dragon.cn/github/issue/DIYgod/RSSHub

🚏 Route: /github/issue/:user/:repo?

βš™οΈ Parameters:

  • user, required - GitHub username
  • repo, optional - GitHub repo name, RSSHub by default

Keyword (Description with table)​

<Route author="DIYgod" example="/pixiv/search/Nezuko/popular/2" path="/pixiv/search/:keyword/:order?/:mode?" paramsDesc={['keyword', 'rank mode, empty or other for time order, `popular` for popular order, `date` by default', 'filte R18 content, see table below, empty by default']}>

| only not R18 | only R18 | no filter      |
| ------------ | -------- | -------------- |
| safe         | r18      | empty or other |

</Route>

πŸ‘¨β€πŸ’» Author: @DIYgod

πŸ’‘ Example: https://rsshub.mlj-dragon.cn/pixiv/search/Nezuko/popular/2

🚏 Route: /pixiv/search/:keyword/:order?/:mode?

βš™οΈ Parameters:

  • keyword, required - keyword
  • order, optional - rank mode, empty or other for time order, popular for popular order, date by default
  • mode, optional - filte R18 content, see table below, empty by default
only not R18only R18no filter
safer18empty or other

Custom containers​

If you'd like to provide additional information about a particular route, you can use these custom containers:

<details>
  <summary>Click to expand</summary>
  This is a detail block. Title is optional and does not support Markdown.
</details>

:::note

This is a note.

:::

:::tip[Tips title]

Title is optional.

:::

:::info

Supprts Markdown.

:::

:::warning

Add a empty line around the starting and ending directive `:::`

:::

:::danger

Otherwise the content may not be rendered properly.

:::
Details

Click to expand This is a detail block. Title is optional and does not support Markdown.

note

This is a note.

Tips title

Title is optional.

info

Supprts Markdown.

warning

Add a empty line around the starting and ending directive :::

danger

Otherwise the content may not be rendered properly.

Other components​

In addition to the aforementioned component properties, there are several other properties you can use to provide more information about your route:

  • anticrawler: set to 1 if the target website has an anti-crawler mechanism.
  • puppeteer: set to 1 if the feed uses puppeteer.
  • radar: set to 1 if the feed has a radar rule.
  • configRequired: set to 1 if the feed requires extra configuration through environment variables.
  • supportBT: set to 1 if the feed supports BitTorrent.
  • supportPodcast: set to 1 if the feed supports podcasts.
  • supportScihub: set to 1 if the feed supports Sci-Hub.

By using these properties, you can provide valuable information to users and make it easier for them to understand and use your route. Adding these properties to your route documentation will add a badge in front of it.

<Route author="HenryQW" example="/github/issue/DIYgod/RSSHub" path="/github/issue/:user/:repo?" paramsDesc={['GitHub username', 'GitHub repo name, `RSSHub` by default']} anticrawler="1" puppeteer="1" radar="1" configRequired="1" supportBT="1" supportPodcast="1" supportScihub="1" />

🚨 Strict anti-crawlingπŸ”„ Support BTπŸŽ™οΈ Support PodcastπŸ§ͺ Support Sci-Hub🎭 Rely on Puppeteerβš™οΈ Config requiredπŸ” Support Radar

πŸ‘¨β€πŸ’» Author: @HenryQW

πŸ’‘ Example: https://rsshub.mlj-dragon.cn/github/issue/DIYgod/RSSHub

🚏 Route: /github/issue/:user/:repo?

βš™οΈ Parameters:

  • user, required - GitHub username
  • repo, optional - GitHub repo name, RSSHub by default

Other things to keep in mind​

  • When documenting a route, use a level 3 heading (###). If the route documentation doesn't have a main section heading, add a level 2 heading (##).
  • Leave a blank line between each heading and the following content. This will help ensure that your documentation can be built successfully.
  • If the documentation contains a large table, it is suggested to put it inside a details container
  • Components can be written in two ways: as a self-closing tag (<Route .../>) or as a pair of tags (<Route>...</Route>).
  • Remember to close the tag!
  • Don't forget to run the following command in the root directory of the project to check and format your code before committing and submitting a merge request:
pnpm run format