Comments (8)
interesting!
This project is very much for stuff hosted on github/gitlab/bitbucket. So, repositories, that link to other markdown files in that repository. I think we even support such URLs, but in the way that /remarkjs/remark-validate-links/blob/main/readme.md
and /remarkjs/remark-validate-links
point to the readme here! So adding a feature like that, probably also comes with the need for other features (e.g., swapping md for html or the dirname), and I’m wondering whether that makes sense in this project or should be something else?
from remark-validate-links.
/remarkjs/remark-validate-links/blob/main/readme.md
and/remarkjs/remark-validate-links
point to the readme here
Aha, I guess these are root-relative links to GitHub then? These I would actually count as "external links", but I can see how they have all of the characteristics of a normal root-relative link.
I think that the 95% case can probably be handled with a general resolution scheme, with a configuration option of baseDir
or similar that would be removed from the link.
For example, this configuration...
module.exports = {
plugins: [
[
"remark-validate-links",
{
baseDir: '/remarkjs/remark-validate-links',
},
],
],
}
...along with this link in Markdown...
[link](/remarkjs/remark-validate-links/docs/configuration)
...would search for the following files in the repo to see if it will be a broken link:
/docs/configuration.md
/docs/configuration/index.md
This would allow for a lot of cases for Markdown projects, both:
- for rendering on GitHub/GitLab/Bitbucket
- separate from these platforms (eg. Gatsby, Next.js, 11ty, etc)
However, since your library has a focus on these platforms, there could be two or more special cases added for these platforms:
1. Add check for readme.md
files
Since these platforms use readme.md
instead of index.md
, add a single extra check:
/docs/configuration.md
/docs/configuration/index.md
+/docs/configuration/readme.md
2. Add check for non-blob paths
In your first example, there was a GitHub-specific blob
path (/remarkjs/remark-validate-links/blob/main/readme.md
).
If it's a link like your example, pointing at the default branch, then it can probably be special-cased to look for /readme.md
(remove the GitHub-specific /\/blob\/[^/]+\//
, after removing the baseDir
).
However, if it is not the default branch, this is more complicated, because it takes into account branches and even commits. For this, it probably makes sense to try to resolve this as an external link (or just not support these links with proprietary branch / commit strings in them).
For example, this configuration...
module.exports = {
plugins: [
[
"remark-validate-links",
{
baseDir: '/remarkjs/remark-validate-links',
},
],
],
}
...along with this link in Markdown...
[link](/remarkjs/remark-validate-links/blob/non-default-branch/readme.md)
...would check the following external links:
https://github.com/remarkjs/remark-validate-links/blob/non-default-branch/readme.md
from remark-validate-links.
Oh, just reading in find.js
, I see you're already trying to do some resolution of GitHub/etc root-relative links, with no support for branches, got it :)
remark-validate-links/lib/find/find.js
Lines 190 to 223 in ca235ff
from remark-validate-links.
So I suppose the changes proposed by this issue would have to be somewhere in here:
remark-validate-links/lib/find/find.js
Lines 190 to 215 in ca235ff
Specifically, to add a separate branch that would resolve root-relative links to file paths with baseDir
or similar config setting.
from remark-validate-links.
Say I have a package.json
like this:
{
"name": "example",
"scripts": {
"test": "remark ."
},
"remarkConfig": {
"plugins": [
[
"validate-links",
{
"repo": "x/y"
}
]
]
},
"devDependencies": {
"remark-cli": "^8.0.1",
"remark-validate-links": "^10.0.2"
}
}
A readme.md
file:
[a](/x/y/blob/main/docs/non-existent/)
[b](/x/y/blob/main/docs/exists/#readme)
[c](/x/y/blob/main/docs/exists/#non-existent2)
And a docs/exists/readme.md
file:
Hi!
Now, running npm test
yields:
$ nr test
> example@ test /Users/tilde/Projects/oss/example
> remark .
docs/exists/readme.md: no issues found
readme.md
1:1-1:39 warning Link to unknown file: `docs/non-existent` missing-file remark-validate-links
3:1-3:47 warning Link to unknown heading in `docs/exists`: `non-existent2` missing-heading-in-file remark-validate-links
⚠ 2 warnings
As you can see, the links are checked. remark-validate-links
correctly sees that non-existent
does not exist, that docs/exists
is a folder with a readme.md
, but that it does not have a #non-existent2
header.
This is to say, we do support full urls with a hostname (https://github.com/x/y/blob/main/docs/exists
), absolute paths (/x/y/blob/main/docs/exists
), relative paths and whatnot too.
What this project does is resolve all URLs, as if the markdown was rendered on GH, Gl, Bb. It checks whether they would work or not.
What you mention here:
...along with this link in Markdown...
[link](/remarkjs/remark-validate-links/docs/configuration)
...would search for the following files in the repo to see if it will be a broken link:
/docs/configuration.md /docs/configuration/index.md
This would allow for a lot of cases for Markdown projects, both:
That sort of works as shown above, but it does that with readme.md
files. (And, blob/branch
is needed).
So, I’d say the question, support root-relative links (absolute links), is already solved. Just in a different way than what you expected. Thus, to come back to the original problem
On large sites with a lot of moving files or large directory structures, updating relative links can be a pain.
Root relative links can also avoid any ambiguity that can be caused by using the same path ending and file name between multiple files.
Can you tell me more about this?
from remark-validate-links.
Sure. Here's an example:
- A user has a website or blog built with MD/MDX files in a
src/pages
directory (eg. on Gatsby, Next.js, 11ty, etc) - The MD/MDX files link amongst themselves. These links will become links on the built website:
This link above would link to the built result of the file
To read more, check out [the docs](/lib-2/docs) about `lib-2`!
/src/pages/lib-2/docs.md
. The configuration here would probably look something like:baseDir: '/src/pages'
- Optional (to illustrate ambiguity): This website or blog has a structure that is repeated across multiple pages (eg. a
docs.md
file ordocs
folder inside many different folders). It's clearer and less ambiguous to use root-relative links here such as/lib-2/docs
. - Optional (to illustrate files / directories that move): This is a fast-moving project, so the structure of the site ends up changing every 6 months to 2 years.
- Users want to be able to be certain that their links work and continue to work
With any sort of renaming or structure changes, it can lead to a lot of error-prone manual work, if there is no automation such as a link checker involved (and users want the guarantees mentioned in point 5).
Does this clarify anything?
from remark-validate-links.
I ended up building this CLI tool in the meantime:
https://github.com/upleveled/mdx-local-link-checker
This supports links to local MDX files, along with the following features:
- checking a specific folder at a path
- ignoring anything at a provided blob pattern
- checking a specific folder with a different root-relative path
# Check the current directory with no ignore patterns
mdx-local-link-checker
# Check the src/pages folder, ignoring anything in a
# folder called "books" (at any depth)
mdx-local-link-checker src/pages src/pages "/books/**"
# Check the src/pages folder, ignoring anything in a
# folder called "books" or "slide-decks" (at any depth)
mdx-local-link-checker src/pages src/pages "/(books|slide-decks)/**"
# Check only the docs folder with the src/pages
# folder set to be the base path (for root-relative
# links such as "/docs/router")
mdx-local-link-checker src/pages/docs src/pages
from remark-validate-links.
So in case urlConfig
or some other configuration setting would be changed in remark-validate-links
(unlikely, given that this project is GitHub / GitLab / Bitbucket focused), maybe it could work like this:
Config:
baseDir: '/src/pages',
extension: 'mdx',
<repository root>/src/pages/lib-1/index.mdx
To read more, check out [the docs](/lib-2/docs) about `lib-2`!
The link above would be resolved to the file <repository root>/src/pages/lib-2/docs.mdx
(maybe the extension
config is superfluous and could just be replaced by a number of supported extensions which would be checked eg. .md
, .mdx
, maybe also .html
)
from remark-validate-links.
Related Issues (20)
- External links always report as failures HOT 10
- How to pass `urlConfig` HOT 10
- Fails on projects not versioned with Git HOT 6
- Support linking to anchors in directories HOT 15
- Error when using with Bazel HOT 4
- No warning or error in case of missing reference HOT 3
- Link checker fails on a matching substring HOT 6
- Multiple hyphens in a row are not collapsed in headings HOT 4
- Emoji headings are not supported HOT 1
- Images in headings not slugged correctly HOT 6
- Links are failing when the link is using any of the restricted names like "constructor"/"concat" etc. HOT 2
- `missing-heading-in-file` after upgrade to latest `remark-cli` (v10) HOT 9
- Links checks are failing when the header contains any special character in it. HOT 1
- Support [[wikilinks]] HOT 5
- Validate links for Foliant projects HOT 7
- Headings with inline comments are slugged incorrectly HOT 5
- Nonexistent reference-style links don't cause an error HOT 3
- Does not catch bad links that use absolute paths to repo root HOT 5
- Allow selection between warning, error and ignoring regarding the validity of links HOT 9
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from remark-validate-links.