From ede47e9e2f0a2fcb70aacaab6bac99ff12b80c87 Mon Sep 17 00:00:00 2001 From: Lars Kappert Date: Fri, 24 Nov 2023 15:43:31 +0100 Subject: [PATCH] Fix up some links + plugin list --- packages/docs/scripts/generate-plugin-docs.ts | 19 +++++++++------ .../content/docs/guides/handling-issues.md | 17 ++++++------- .../content/docs/guides/troubleshooting.md | 24 ++++++++++--------- .../content/docs/reference/known-issues.md | 3 ++- 4 files changed, 34 insertions(+), 29 deletions(-) diff --git a/packages/docs/scripts/generate-plugin-docs.ts b/packages/docs/scripts/generate-plugin-docs.ts index 4f921a359..733900333 100644 --- a/packages/docs/scripts/generate-plugin-docs.ts +++ b/packages/docs/scripts/generate-plugin-docs.ts @@ -3,6 +3,7 @@ import fs from 'node:fs/promises'; import path from 'node:path'; import { fileURLToPath } from 'node:url'; import prettier from 'prettier'; +import remarkDirective from 'remark-directive'; import remarkFrontmatter from 'remark-frontmatter'; import remarkParse from 'remark-parse'; import remarkStringify from 'remark-stringify'; @@ -29,6 +30,7 @@ const writeTree = async (tree, filePath) => { const file = await unified().run(tree); const markdown = unified() .use(remarkFrontmatter, ['yaml']) + .use(remarkDirective) .use(remarkStringify, { bullet: '-', }) @@ -101,13 +103,16 @@ const frontmatter = u('yaml', `title: Plugins\ntableOfContents: false`); const tree = u('root', [ frontmatter, - u( - 'list', - { spread: false, ordered: false }, - plugins.map(plugin => - u('listItem', [u('link', { title: plugin[0], url: `./plugins/${plugin[1]}.md` }, [u('text', plugin[0])])]) - ) - ), + u('containerDirective', { name: 'section{.plugins}' }, [ + u( + 'list', + { spread: false, ordered: false }, + plugins.map(plugin => + u('listItem', [u('link', { title: plugin[0], url: `./plugins/${plugin[1]}.md` }, [u('text', plugin[0])])]) + ) + ), + u('paragraph'), + ]), ]); console.log(`Writing plugin list to plugins.md`); diff --git a/packages/docs/src/content/docs/guides/handling-issues.md b/packages/docs/src/content/docs/guides/handling-issues.md index b5925ff7c..a4bf7e158 100644 --- a/packages/docs/src/content/docs/guides/handling-issues.md +++ b/packages/docs/src/content/docs/guides/handling-issues.md @@ -75,13 +75,13 @@ yet, or open an issue to request it. Files might be imported through files with non-standard extensions like `.astro`, `.mdx`, `.vue` or `.svelte`. These files are not included by default. -See [compilers][9] for more details on how to include them. +See [compilers][7] for more details on how to include them. ### Integrated Monorepos Multiple instances of configuration files like `.eslintrc` and `jest.config.json` across the repository may be reported as unused when working -in a (mono)repo with a single `package.json`. See [integrated monorepos][7] for +in a (mono)repo with a single `package.json`. See [integrated monorepos][8] for more details and how to configure plugins to target those configuration files. ### Build artifacts and ignored files @@ -95,7 +95,7 @@ manually for better or more consistent results. ## Unused dependencies Dependencies imported in unused files are reported as unused dependencies. -That's why it's strongly recommended to try and remedy [unused files][8] first. +That's why it's strongly recommended to try and remedy [unused files][9] first. This solves many cases of reported unused dependencies. :::tip @@ -122,7 +122,7 @@ an existing one. Dependencies might be imported from files with non-standard extensions like `.astro`, `.mdx`, `.vue` or `.svelte`. These files are not included by default. -See [compilers][9] for more details on how to include them. +See [compilers][7] for more details on how to include them. ### Unreachable Code @@ -255,15 +255,12 @@ report unused exports in entry files. [4]: ../explanations/entry-files.md#plugins [5]: ./writing-a-plugin.md [6]: ../reference/plugins.md -[7]: ../features/integrated-monorepos.md -[8]: #unused-files -[9]: ../features/compilers.md +[7]: ../features/compilers.md +[8]: ../features/integrated-monorepos.md +[9]: #unused-files [10]: #unlisted-binaries [11]: https://eslint.org/docs/head/use/configure/configuration-files-new [12]: ../features/monorepos-and-workspaces.md#lint-a-single-workspace [13]: ../reference/jsdoc-tsdoc-tags.mdx [14]: ../reference/configuration.md#ignore-exports-used-in-file [15]: ../reference/configuration.md#includeentryexports -[16]: ../features/rules-and-filters.md -[17]: ../features/rules-and-filters.md#rules -[18]: ../reference/configuration.md#ignore diff --git a/packages/docs/src/content/docs/guides/troubleshooting.md b/packages/docs/src/content/docs/guides/troubleshooting.md index fbcd7b8e6..855a61954 100644 --- a/packages/docs/src/content/docs/guides/troubleshooting.md +++ b/packages/docs/src/content/docs/guides/troubleshooting.md @@ -6,14 +6,14 @@ sidebar: We can distinguish two types of issues: -- [Issues reported by Knip](#handling-issues) -- [Exceptions thrown by Knip](#exceptions-thrown-by-knip) +- [Issues reported by Knip][1] +- [Exceptions thrown by Knip][2] ## Issues Reported by Knip This indicates a successful run, but there are unused items (exit code `1`). -Read [handling issues][1] on how to deal with the unused items as reported by +Read [handling issues][3] on how to deal with the unused items as reported by Knip. To better understand why Knip reports what it does, run it in debug mode by adding `--debug` to the command: @@ -33,7 +33,7 @@ This will give a lengthy output, including: Knip (or one of its plugins loading a configuration file) may throw an error, resulting in an unsuccessful run (exit code `2`). You might be encountering a -[known issue][2]. +[known issue][4]. Add `--debug` to the command for more error details to better locate the cause of the error. @@ -44,19 +44,21 @@ Looking to better understand how Knip works? The [entry files][5] and [plugins][6] explanations cover two core concepts. After this you might want to check out features like [production mode][7] and [monorepos & workspaces][8]. -In a more general sense, [Why use Knip?](../explanations/why-use-knip.md) -explains what Knip can do for you. +In a more general sense, [Why use Knip?][9] explains what Knip can do for you. ## Ask for Help If you can't find your answer in any of the aforementioned resources, feel free -to [open an issue on GitHub][3] or discuss it in [the Discord channel][4]. +to [open an issue on GitHub][10] or discuss it in [the Discord channel][11]. -[1]: ../guides/handling-issues.md -[2]: ../reference/known-issues.md -[3]: https://github.com/webpro/knip/issues -[4]: https://discord.gg/r5uXTtbTpc +[1]: #handling-issues +[2]: #exceptions-thrown-by-knip +[3]: ../guides/handling-issues.md +[4]: ../reference/known-issues.md [5]: ../explanations/entry-files.md [6]: ../explanations/plugins.md [7]: ../features/production-mode.md [8]: ../features/monorepos-and-workspaces.md +[9]: ../explanations/why-use-knip.md +[10]: https://github.com/webpro/knip/issues +[11]: https://discord.gg/r5uXTtbTpc diff --git a/packages/docs/src/content/docs/reference/known-issues.md b/packages/docs/src/content/docs/reference/known-issues.md index 16e50acfc..b1c2b042d 100644 --- a/packages/docs/src/content/docs/reference/known-issues.md +++ b/packages/docs/src/content/docs/reference/known-issues.md @@ -43,9 +43,10 @@ Similar to the previous known issue, this is caused through (not by) jiti: TypeError: Reflect.metadata is not a function ``` -[GitHub Issue #355](https://github.com/webpro/knip/issues/355) +[GitHub Issue #355][5] [1]: https://github.com/unjs/jiti [2]: ./configuration.md#ignore [3]: ./configuration.md#plugins [4]: https://github.com/unjs/jiti/issues/174 +[5]: https://github.com/webpro/knip/issues/355