Repository navigation
docs: link to docs by relative file path instead of full URLs - #4882
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
ShaneK
left a comment
There was a problem hiding this comment.
Looks good to me, great work! Just a couple of small wording nits, feel free to take or leave them.
| - [`<Heading>`](https://docusaurus.io/docs/api/misc/@docusaurus/eslint-plugin/prefer-docusaurus-heading) from `@theme/Heading` instead of `<h2>` to `<h6>`. | ||
|
|
||
| Link to another doc by its relative file path, with the extension, such as `[Accordion](./accordion.mdx)` or `[Config](../developing/config.mdx)`. Docusaurus resolves it to the page in the same version, the build fails if the file doesn't exist, and editors can follow it to the file. A JSX prop such as `href` skips that step, so use the URL path without `/docs` or an extension instead: `/api/accordion`, or `/v8/api/accordion` on a v8 page. `npm run lint` flags a link in either form that doesn't follow this. | ||
| Link to another doc by its relative file path, with the extension, such as `[Accordion](./accordion.mdx)` or `[Config](../developing/config.mdx)`. Docusaurus resolves it to the page in the same version, the build fails if the file doesn't exist, and editors can follow it to the file. Don't link to a doc by its full `ionicframework.com/docs` URL, which always opens the current version. A JSX prop such as `href` skips that step, so use the URL path without `/docs` or an extension instead: `/api/accordion`, or `/v8/api/accordion` on a v8 page. `npm run lint` flags a link in either form that doesn't follow this. |
There was a problem hiding this comment.
| Link to another doc by its relative file path, with the extension, such as `[Accordion](./accordion.mdx)` or `[Config](../developing/config.mdx)`. Docusaurus resolves it to the page in the same version, the build fails if the file doesn't exist, and editors can follow it to the file. Don't link to a doc by its full `ionicframework.com/docs` URL, which always opens the current version. A JSX prop such as `href` skips that step, so use the URL path without `/docs` or an extension instead: `/api/accordion`, or `/v8/api/accordion` on a v8 page. `npm run lint` flags a link in either form that doesn't follow this. | |
| Link to another doc by its relative file path, with the extension, such as `[Accordion](./accordion.mdx)` or `[Config](../developing/config.mdx)`. Docusaurus resolves it to the page in the same version, the build fails if the file doesn't exist, and editors can follow it to the file. A JSX prop such as `href` skips that step, so use the URL path without `/docs` or an extension instead: `/api/accordion`, or `/v8/api/accordion` on a v8 page. In either form, don't link to a doc by its full `ionicframework.com/docs` URL, which always opens the current version. `npm run lint` flags a link that doesn't follow this, though it only catches a full URL in a Markdown link. |
Moving the full-URL sentence after the JSX one, since right now "that step" reads like it points back at the full-URL rule instead of Docusaurus resolving the file. The lint claim also needed scoping, because checkJsxLink returns early for anything with a scheme, so a full docs URL in an href or to prop passes while the same URL in a Markdown link gets flagged. I didn't go the other way and add the check to checkJsxLink since it would trip on the canonical and alternate <link> tags in the <head> of docs/index.mdx. This is just a nit though, up to you!
| // A page on this site by its full URL. Archived versions such as `/docs/v3/` | ||
| // are not built from this repo, so they stay full URLs. | ||
| const DOCS_SITE_URL = /^https?:\/\/(www\.)?ionicframework\.com\/docs(?!\/v\d+(\/|$))(\/|$|[?#])/i; |
There was a problem hiding this comment.
| // A page on this site by its full URL. Archived versions such as `/docs/v3/` | |
| // are not built from this repo, so they stay full URLs. | |
| const DOCS_SITE_URL = /^https?:\/\/(www\.)?ionicframework\.com\/docs(?!\/v\d+(\/|$))(\/|$|[?#])/i; | |
| // A page on this site by its full URL. A versioned URL such as `/docs/v3/` or | |
| // `/docs/v8/` opens that version rather than the current one, so it is allowed. | |
| const DOCS_SITE_URL = /^https?:\/\/(www\.)?ionicframework\.com\/docs(?!\/v\d+(\/|$|[?#]))(\/|$|[?#])/i; |
The reason in this comment doesn't cover /docs/v8/, which we do build from this repo, though exempting it is right since a /docs/vN URL opens that version anyway. While I was poking at it I noticed a URL like https://ionicframework.com/docs/v8#something gets flagged with "A full URL always opens the current version", which isn't true for that one, so I added ? and # to the lookahead too. With this change, a v9 page and a v8 page still flag /docs/api/modal and nothing else. Up to you!
There was a problem hiding this comment.
Applied in 22d7a7d, good catch on the # and ? case!
Issue URL: N/A
What is the current behavior?
docs/use a fullionicframework.com/docsURL. A full URL always opens the current version, so once v10 ships, these links on the v9 pages send readers to v10.What is the new behavior?
npm run lintfails on a Markdown link to a doc by its fullionicframework.com/docsURL. Archived versions such as/docs/v3/and static files are still allowed.Does this introduce a breaking change?
Other information
v8 got the same fix in #4879. The next sync into
major-10.0carries this into v9, which makes #4881 unnecessary.How to test
docs/to its fullhttps://ionicframework.com/docs/...URL.npm run lintfails on that line.