From f9cda41946f0b69b703d4c7b39e0c036ecb67edd Mon Sep 17 00:00:00 2001 From: TonyRL Date: Thu, 30 Nov 2023 18:07:46 +0000 Subject: [PATCH] docs: format docs using markdownlint-cli2 --- .github/PULL_REQUEST_TEMPLATE.md | 28 +++++++++---------- .markdownlint.jsonc | 3 +- CODE_OF_CONDUCT.md | 6 ++-- README.md | 2 +- scripts/ansible/README.md | 2 ++ website/README.md | 10 +++---- website/docs/install/config.md | 19 ++++++------- website/docs/{instances.md => instances.mdx} | 0 website/docs/joinus/new-rss/add-docs.md | 12 ++++---- website/docs/joinus/new-rss/start-code.md | 2 +- .../current/install/README.md | 2 +- .../current/install/config.md | 22 +++++++-------- .../current/{instances.md => instances.mdx} | 2 +- .../current/joinus/new-rss/add-docs.md | 10 +++---- .../current/joinus/new-rss/start-code.md | 1 - .../current/joinus/new-rss/submit-route.md | 1 - 16 files changed, 60 insertions(+), 62 deletions(-) rename website/docs/{instances.md => instances.mdx} (100%) rename website/i18n/zh/docusaurus-plugin-content-docs/current/{instances.md => instances.mdx} (75%) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index fb401f50ab..ffce3bbec0 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -31,19 +31,19 @@ If your changes are not related to route, please fill in `routes` section with ` ## New RSS Route Checklist / 新 RSS 路由检查表 -- [ ] New Route / 新的路由 - - [ ] Follows [v2 Script Standard](https://docs.rsshub.app/joinus/advanced/script-standard) / 跟随 [v2 路由规范](https://docs.rsshub.app/zh/joinus/advanced/script-standard) -- [ ] Documentation / 文档说明 - - [ ] EN / 英文文档 - - [ ] CN / 中文文档 -- [ ] Full text / 全文获取 - - [ ] Use cache / 使用缓存 -- [ ] Anti-bot or rate limit / 反爬/频率限制 - - [ ] If yes, do your code reflect this sign? / 如果有, 是否有对应的措施? -- [ ] [Date and time](https://docs.rsshub.app/joinus/advanced/pub-date) / [日期和时间](https://docs.rsshub.app/zh/joinus/advanced/pub-date) - - [ ] Parsed / 可以解析 - - [ ] Correct time zone / 时区正确 -- [ ] New package added / 添加了新的包 -- [ ] `Puppeteer` +- [ ] New Route / 新的路由 + - [ ] Follows [v2 Script Standard](https://docs.rsshub.app/joinus/advanced/script-standard) / 跟随 [v2 路由规范](https://docs.rsshub.app/zh/joinus/advanced/script-standard) +- [ ] Documentation / 文档说明 + - [ ] EN / 英文文档 + - [ ] CN / 中文文档 +- [ ] Full text / 全文获取 + - [ ] Use cache / 使用缓存 +- [ ] Anti-bot or rate limit / 反爬/频率限制 + - [ ] If yes, do your code reflect this sign? / 如果有, 是否有对应的措施? +- [ ] [Date and time](https://docs.rsshub.app/joinus/advanced/pub-date) / [日期和时间](https://docs.rsshub.app/zh/joinus/advanced/pub-date) + - [ ] Parsed / 可以解析 + - [ ] Correct time zone / 时区正确 +- [ ] New package added / 添加了新的包 +- [ ] `Puppeteer` ## Note / 说明 diff --git a/.markdownlint.jsonc b/.markdownlint.jsonc index e426ea78ad..f8f413b279 100644 --- a/.markdownlint.jsonc +++ b/.markdownlint.jsonc @@ -1,5 +1,4 @@ { - "MD007": { "indent": 4 }, // ul-indent - Unordered list indentation "MD013": false, // line-length - Line length "MD014": false, // commands-show-output - Dollar signs used before commands without showing output "MD024": { "siblings_only": true }, // no-duplicate-heading/no-duplicate-header - Multiple headings with the same content @@ -7,5 +6,7 @@ "MD033": false, // no-inline-html - Inline HTML "MD036": false, // no-emphasis-as-heading/no-emphasis-as-header - Emphasis used instead of a heading "MD040": false, // fenced-code-language - Fenced code blocks should have a language specified + "MD041": false, // first-line-heading/first-line-h1 - First line in a file should be a top-level heading + "MD045": false, // no-alt-text - Images should have alternate text (alt text) "MD051": false // link-fragments - Link fragments should be valid } diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index c63af734ae..e452526ecf 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -39,7 +39,7 @@ This Code of Conduct applies within all community spaces, and also applies when ## Enforcement -Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at i@diygod.me. All complaints will be reviewed and investigated promptly and fairly. +Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at . All complaints will be reviewed and investigated promptly and fairly. All community leaders are obligated to respect the privacy and security of the reporter of any incident. @@ -74,11 +74,11 @@ Community leaders will follow these Community Impact Guidelines in determining t ## Attribution This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.0, -available at https://www.contributor-covenant.org/version/2/0/code_of_conduct.html. +available at . Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity). [homepage]: https://www.contributor-covenant.org For answers to common questions about this code of conduct, see the FAQ at -https://www.contributor-covenant.org/faq. Translations are available at https://www.contributor-covenant.org/translations. +. Translations are available at . diff --git a/README.md b/README.md index 53ca3bfe23..8794050df9 100644 --- a/README.md +++ b/README.md @@ -78,7 +78,7 @@ Recurring donors will be rewarded via express issue response, or even have your - Become a Sponser on [Patreon](https://www.patreon.com/DIYgod) - Become a Sponser on [Open Collective](https://opencollective.com/RSSHub) - Become a Sponser on [爱发电](https://afdian.net/@diygod) -- Contact us directly: i@diygod.me +- Contact us directly: ### One-time Donation diff --git a/scripts/ansible/README.md b/scripts/ansible/README.md index 50cae9b717..3d6ea29196 100644 --- a/scripts/ansible/README.md +++ b/scripts/ansible/README.md @@ -5,6 +5,7 @@ Ansible playbook to deploy [RSSHub](https://github.com/DIYgod/RSSHub) on bare-me Requires sudo permission ## Usage + On `Ubuntu 20.04`, [install ansible](https://www.digitalocean.com/community/tutorials/how-to-install-and-configure-ansible-on-ubuntu-20-04), then ```bash @@ -12,6 +13,7 @@ sudo ansible-playbook rsshub.yaml ``` ## Development + Install `vagrant`, then ```bash diff --git a/website/README.md b/website/README.md index cdaeb3067d..36e55f9c8e 100644 --- a/website/README.md +++ b/website/README.md @@ -1,14 +1,14 @@ # Website -This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator. +This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator. -### Installation +## Installation ``` $ pnpm ``` -### Local Development +## Local Development ``` $ pnpm start @@ -16,7 +16,7 @@ $ pnpm start This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server. -### Build +## Build ``` $ pnpm build @@ -24,7 +24,7 @@ $ pnpm build This command generates static content into the `build` directory and can be served using any static contents hosting service. -### Deployment +## Deployment Using SSH: diff --git a/website/docs/install/config.md b/website/docs/install/config.md index 8202d43c86..03ae506a7c 100644 --- a/website/docs/install/config.md +++ b/website/docs/install/config.md @@ -294,9 +294,10 @@ See docs of the specified route and `lib/config.js` for detailed information. - `DISCORD_AUTHORIZATION`: Discord authorization token, can be found in the header of XHR requests after logging in Discord web client ### Discourse + - `DISCOURSE_CONFIG_{id}`: `id` could be arbitrary number or string, while the value should be the format of `{"link":link,"key":key}`, where: - - `link` is the link to the forum. - - `key` is the access key for the forum API, which you can refer to [this snippet](https://pastebin.com/YbLCgdWW) to obtain one. Ensure that this key is granted sufficient permission. + - `link` is the link to the forum. + - `key` is the access key for the forum API, which you can refer to [this snippet](https://pastebin.com/YbLCgdWW) to obtain one. Ensure that this key is granted sufficient permission. ### Discuz cookie @@ -364,8 +365,8 @@ Warning: Two Factor Authentication is **not** supported. ### Email - `EMAIL_CONFIG_{email}`: Mail setting, replace `{email}` with the email account, replace `@` and `.` in email account with `_`, e.g. `EMAIL_CONFIG_xxx_gmail_com`. The value is in the format of `password=password&host=server&port=port`, eg: - - Linux env: `EMAIL_CONFIG_xxx_qq_com="password=123456&host=imap.qq.com&port=993"` - - docker env: `EMAIL_CONFIG_xxx_qq_com=password=123456&host=imap.qq.com&port=993`, please do not include quotations `'`,`"` + - Linux env: `EMAIL_CONFIG_xxx_qq_com="password=123456&host=imap.qq.com&port=993"` + - docker env: `EMAIL_CONFIG_xxx_qq_com=password=123456&host=imap.qq.com&port=993`, please do not include quotations `'`,`"` - Note: socks5h proxy is not supported due to the limit of email lib `ImapFlow` @@ -449,8 +450,6 @@ For scientific journal routes - `SPOTIFY_CLIENT_ID`: Client ID of the application - `SPOTIFY_CLIENT_SECRET`: Client secret of the application -### Spotify - For user data related routes - `SPOTIFY_REFRESHTOKEN`: The refresh token of the user from the Spotify application. Check [this gist](https://gist.github.com/outloudvi/d1bbeb5e989db5385384a223a7263744) for detailed information. @@ -485,11 +484,11 @@ For user data related routes [API Key application](https://console.developers.google.com/) - All routes: - - `YOUTUBE_KEY`: YouTube API Key, support multiple keys, split them with `,` + - `YOUTUBE_KEY`: YouTube API Key, support multiple keys, split them with `,` - Extra requirements for subscriptions route: - - `YOUTUBE_CLIENT_ID`: YouTube API OAuth 2.0 client ID - - `YOUTUBE_CLIENT_SECRET`: YouTube API OAuth 2.0 client secret - - `YOUTUBE_REFRESH_TOKEN`: YouTube API OAuth 2.0 refresh token. Check [this gist](https://gist.github.com/Kurukshetran/5904e8cb2361623498481f4a9a1338aa) for detailed instructions. + - `YOUTUBE_CLIENT_ID`: YouTube API OAuth 2.0 client ID + - `YOUTUBE_CLIENT_SECRET`: YouTube API OAuth 2.0 client secret + - `YOUTUBE_REFRESH_TOKEN`: YouTube API OAuth 2.0 refresh token. Check [this gist](https://gist.github.com/Kurukshetran/5904e8cb2361623498481f4a9a1338aa) for detailed instructions. ### ZodGame diff --git a/website/docs/instances.md b/website/docs/instances.mdx similarity index 100% rename from website/docs/instances.md rename to website/docs/instances.mdx diff --git a/website/docs/joinus/new-rss/add-docs.md b/website/docs/joinus/new-rss/add-docs.md index 0232ae5c7f..a007ecfb4a 100644 --- a/website/docs/joinus/new-rss/add-docs.md +++ b/website/docs/joinus/new-rss/add-docs.md @@ -72,12 +72,12 @@ To add documentation to your route, use the `Route` React component. It works li - `example`: The route example, with a leading `/` - `path`: The route path, which should be the same as the key in [`maintainer.js`](/joinus/new-rss/before-start#understand-the-basics-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. + - 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 diff --git a/website/docs/joinus/new-rss/start-code.md b/website/docs/joinus/new-rss/start-code.md index f7a49801c7..64d4298d00 100644 --- a/website/docs/joinus/new-rss/start-code.md +++ b/website/docs/joinus/new-rss/start-code.md @@ -807,6 +807,6 @@ You can find all the possible values of `request.resourceType()` [here](https:// In the code above, you'll see that `waitUntil: 'domcontentloaded'` is used in the page.goto() function. This is a Puppeteer option that tells it when to consider a navigation successful. You can find all the possible values and their meanings [here](https://pptr.dev/api/puppeteer.page.goto/#remarks). -It's worth noting that `domcontentloaded `waits for a shorter time than the default value `load`, and `networkidle0` may not be suitable for websites that keep sending background telemetry or fetching data. +It's worth noting that `domcontentloaded`waits for a shorter time than the default value `load`, and `networkidle0` may not be suitable for websites that keep sending background telemetry or fetching data. Additionally, it's important to avoid waiting for a specific timeout and instead wait for a selector to appear. Waiting for a timeout is inaccurate, as it depends on the load of the Puppeteer instance. diff --git a/website/i18n/zh/docusaurus-plugin-content-docs/current/install/README.md b/website/i18n/zh/docusaurus-plugin-content-docs/current/install/README.md index e0814d0a6d..04ba976244 100644 --- a/website/i18n/zh/docusaurus-plugin-content-docs/current/install/README.md +++ b/website/i18n/zh/docusaurus-plugin-content-docs/current/install/README.md @@ -324,7 +324,7 @@ Heroku [不再](https://blog.heroku.com/next-chapter) 提供免费服务。 ### 自动更新部署 1. 将 RSSHub [分叉（fork）](https://github.com/DIYgod/RSSHub/fork) 到自己的账户下。 -2. 把自己的分叉部署到 Heroku：`https://heroku.com/deploy?template=URL`，其中 `URL` 改为分叉地址 （例如 `https://github.com/USERNAME/RSSHub`)。 +2. 把自己的分叉部署到 Heroku：`https://heroku.com/deploy?template=URL`，其中 `URL` 改为分叉地址 （例如 `https://github.com/USERNAME/RSSHub`）。 3. 检查 Heroku 设置，随代码库更新自动部署。 4. 安装 [Pull](https://github.com/apps/pull) 应用，定期将 RSSHub 改动自动同步至你的分叉。 diff --git a/website/i18n/zh/docusaurus-plugin-content-docs/current/install/config.md b/website/i18n/zh/docusaurus-plugin-content-docs/current/install/config.md index dba54a0abf..4ff2f005cf 100644 --- a/website/i18n/zh/docusaurus-plugin-content-docs/current/install/config.md +++ b/website/i18n/zh/docusaurus-plugin-content-docs/current/install/config.md @@ -292,8 +292,8 @@ RSSHub 支持使用访问密钥 / 码，允许清单和拒绝清单三种方式 ### Discourse - `DISCOURSE_CONFIG_{id}`: 一个 Discourse 驱动的论坛的配置信息， `id` 可自由设定为任意数字或字符串。值应形如`{"link":link,"key":key}`。其中： - - `link`：论坛的链接。 - - `key`访问论坛 API 的密钥，可参考 [此处代码](https://pastebin.com/YbLCgdWW) 以获取。需要确保有足够权限访问对应资源。 + - `link`：论坛的链接。 + - `key`访问论坛 API 的密钥，可参考 [此处代码](https://pastebin.com/YbLCgdWW) 以获取。需要确保有足够权限访问对应资源。 ### Discuz @@ -435,8 +435,6 @@ RSSHub 支持使用访问密钥 / 码，允许清单和拒绝清单三种方式 - `SPOTIFY_CLIENT_ID`: Spotify 应用的 client ID - `SPOTIFY_CLIENT_SECRET`: Spotify 应用的 client secret -### Spotify - 用户相关路由 - `SPOTIFY_REFRESHTOKEN`：用户在此 Spotify 应用的 refresh token。可以利用 [此 gist](https://gist.github.com/outloudvi/d1bbeb5e989db5385384a223a7263744) 获取。 @@ -471,11 +469,11 @@ RSSHub 支持使用访问密钥 / 码，允许清单和拒绝清单三种方式 [申请地址](https://console.developers.google.com/) - 全部路由 - - `YOUTUBE_KEY`: YouTube API Key，支持多个 key，用英文逗号 `,` 隔开 + - `YOUTUBE_KEY`: YouTube API Key，支持多个 key，用英文逗号 `,` 隔开 - 订阅列表路由额外设置 - - `YOUTUBE_CLIENT_ID`: YouTube API 的 OAuth 2.0 客户端 ID - - `YOUTUBE_CLIENT_SECRET`: YouTube API 的 OAuth 2.0 客户端 Secret - - `YOUTUBE_REFRESH_TOKEN`: YouTube API 的 OAuth 2.0 客户端 Refresh Token。可以按照 [此 gist](https://gist.github.com/Kurukshetran/5904e8cb2361623498481f4a9a1338aa) 获取。 + - `YOUTUBE_CLIENT_ID`: YouTube API 的 OAuth 2.0 客户端 ID + - `YOUTUBE_CLIENT_SECRET`: YouTube API 的 OAuth 2.0 客户端 Secret + - `YOUTUBE_REFRESH_TOKEN`: YouTube API 的 OAuth 2.0 客户端 Refresh Token。可以按照 [此 gist](https://gist.github.com/Kurukshetran/5904e8cb2361623498481f4a9a1338aa) 获取。 ### ZodGame @@ -558,13 +556,13 @@ Web 版认证 token 和 iOS 内购回执认证 token 只需选择其一填入即 - `SEHUATANG_COOKIE`: 登陆色花堂后的 cookie 值。 -### 邮箱 邮件列表路由： +### 邮箱 邮件列表路由 - `EMAIL_CONFIG_{email}`: 邮箱设置，替换 `{email}` 为 邮箱账号，邮件账户的 `@` 与 `.` 替换为 `_`，例如 `EMAIL_CONFIG_xxx_qq_com`。Linux 内容格式为 `password=密码&host=服务器&port=端口`，docker 内容格式为 `password=密码&host=服务器&port=端口`，例如： - - Linux 环境变量：`EMAIL_CONFIG_xxx_qq_com="password=123456&host=imap.qq.com&port=993"` - - docker 环境变量：`EMAIL_CONFIG_xxx_qq_com=password=123456&host=imap.qq.com&port=993`，请勿添加引号 `'`，`"`。 + - Linux 环境变量：`EMAIL_CONFIG_xxx_qq_com="password=123456&host=imap.qq.com&port=993"` + - docker 环境变量：`EMAIL_CONFIG_xxx_qq_com=password=123456&host=imap.qq.com&port=993`，请勿添加引号 `'`，`"`。 -- 注意：邮箱的路由不支持使用 socks5h 的代理，主要是受 `ImapFlow` 这个第三方库的限制，使用的时候需要注意。 +- 注意：邮箱的路由不支持使用 socks5h 的代理，主要是受 `ImapFlow` 这个第三方库的限制，使用的时候需要注意。 ### 网易云歌单 diff --git a/website/i18n/zh/docusaurus-plugin-content-docs/current/instances.md b/website/i18n/zh/docusaurus-plugin-content-docs/current/instances.mdx similarity index 75% rename from website/i18n/zh/docusaurus-plugin-content-docs/current/instances.md rename to website/i18n/zh/docusaurus-plugin-content-docs/current/instances.mdx index 3b14b3f6de..8a6308072a 100644 --- a/website/i18n/zh/docusaurus-plugin-content-docs/current/instances.md +++ b/website/i18n/zh/docusaurus-plugin-content-docs/current/instances.mdx @@ -8,7 +8,7 @@ | URL | Location | Maintainer | Online | | --- | --- | --- | --- | -| https://rsshub.app | 🇺🇸 | [DIYgod](https://diygod.cc) | ![](https://img.shields.io/website.svg?label=&url=https://rsshub.app/test/cache) | +| [rsshub.app](https://rsshub.app) | 🇺🇸 | [DIYgod](https://diygod.cc) | ![](https://img.shields.io/website.svg?label=&url=https://rsshub.app/test/cache) | ## Public diff --git a/website/i18n/zh/docusaurus-plugin-content-docs/current/joinus/new-rss/add-docs.md b/website/i18n/zh/docusaurus-plugin-content-docs/current/joinus/new-rss/add-docs.md index 6fad306da3..b945ef94c4 100644 --- a/website/i18n/zh/docusaurus-plugin-content-docs/current/joinus/new-rss/add-docs.md +++ b/website/i18n/zh/docusaurus-plugin-content-docs/current/joinus/new-rss/add-docs.md @@ -82,11 +82,11 @@ pnpm run start - `example`：路由示例，以 `/` 开头 - `path`：路由，应与添加命名空间后 [maintainer.js](/zh/joinus/new-rss/before-start#maintainerjs) 中的键相同。在之前的教程中，它为 `/github/issue/:user/:repo?` - `paramsDesc`：路由参数描述，以字符串数组形式，支持 Markdown。 - - 描述必须按照它们在路由中出现的顺序。 - - 描述的数量**应**与 `path` 中的参数数量匹配。如果漏掉一个描述，则构建过程会失败。 - - 以 `?`，`*` 或 `+` 结尾的路由参数将自动分别标记为`可选`，`零个或多个`或`一个或多个`，无须再次提及。 - - 没有符号后缀的路由参数将自动标记为`必选` - - 如果参数是可选的，请提及其默认值。 + - 描述必须按照它们在路由中出现的顺序。 + - 描述的数量**应**与 `path` 中的参数数量匹配。如果漏掉一个描述，则构建过程会失败。 + - 以 `?`，`*` 或 `+` 结尾的路由参数将自动分别标记为`可选`，`零个或多个`或`一个或多个`，无须再次提及。 + - 没有符号后缀的路由参数将自动标记为`必选` + - 如果参数是可选的，请提及其默认值。 ## 文档示例 diff --git a/website/i18n/zh/docusaurus-plugin-content-docs/current/joinus/new-rss/start-code.md b/website/i18n/zh/docusaurus-plugin-content-docs/current/joinus/new-rss/start-code.md index a7a81d817f..5b4e68f1a8 100644 --- a/website/i18n/zh/docusaurus-plugin-content-docs/current/joinus/new-rss/start-code.md +++ b/website/i18n/zh/docusaurus-plugin-content-docs/current/joinus/new-rss/start-code.md @@ -501,7 +501,6 @@ module.exports = async (ctx) => { 我们的 RSS 订阅源目前缺少内容。必须设置 `item` 才能添加内容。以下是一个示例： - ```js const buildData = require('@/utils/common-config'); diff --git a/website/i18n/zh/docusaurus-plugin-content-docs/current/joinus/new-rss/submit-route.md b/website/i18n/zh/docusaurus-plugin-content-docs/current/joinus/new-rss/submit-route.md index 61da1bbc9d..5a5eafc19e 100644 --- a/website/i18n/zh/docusaurus-plugin-content-docs/current/joinus/new-rss/submit-route.md +++ b/website/i18n/zh/docusaurus-plugin-content-docs/current/joinus/new-rss/submit-route.md @@ -93,7 +93,6 @@ NOROUTE 此检查表将帮助您确保您的 PR 包含所有必要的组件。虽然您不必勾选所有项目，以使您的 PR 合并，但请确保您的新路由遵循 [路由规范](/zh/joinus/advanced/script-standard)。这是所有新路由的强制性要求。 - ```md - [ ] 新的路由 New Route ```