nodejs.dev
nodejs.dev copied to clipboard
nodejs
Broken internal links in docs page
Description
The internal links to modules or sub pages are broken when reading the docs.
Steps to reproduce
An example can be gotten by visiting this page and clicking on the timers link.
You will have to click the clearImmediate option from the side navigation see issue #902
Expected result
It should open the timers sub page - when issue #902 is solved, or have the correct url.
Actual result
You get a 404 error.
I think this is as a result of directly importing the docs from the old site. I would like to work on this if I'm told a clear course of action, or would the original doc files be edited to reflect the current navigation structure?
Environment
- OS Version:
- Browser Version:
Been thinking about this issue today. I believe a good portion of the docs are generated through gatsby-node, however I was thinking the issue may be that the url ends in /docs with #placeholder-page-called-timer is the only navigation from the end of docs (like this 👉 /docs#placeholder-page-called-timer)
may try to fix this by adding the specific page - in this case Timer - to the url then maybe the pages will work properly /docs/timer/#placeholder-header-under-timer-page
current, live site URL example https://nodejs.org/api/fs.html#fs_callback_example
Both of you are correct. Anything in /learn is generated from gatsby-node the *.md files are in /documentation.
The API docs are loaded from https://nodejs.org/dist/v14.9.0/docs/api/all.json or the version you select.
For example the below object is from the Buffer section. We are using desc as the main content of the docs
At the very end it includes buffer.html which doesn't exist.
desc: "<ul>↵<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a></li>↵</ul>↵<p>Used to handle binary data. See the <a href="buffer.html">buffer section</a>.</p>"
meta: {added: ["v0.1.103"], changes: []}
name: "Buffer"
textRaw: "Class: `Buffer`"
type: "global"
One approach might be to do a regex for an href <a href="buffer.html">Buff</a> that has .html in it. and replace that with a gatsby <Link> <Link to="/foo">Buffer </Link>
I don't think this is possible right now because the site is already built at this stage.
We could do the above if during the build process we made the api request to /all.json did our change and then we could query graphql as usual..
Another idea is to ditch all.json and switch to the i18n npm package. With this package we can then load the same content as md files here
Next steps: option 1:
- run a crawler on nodejs.dev/docs to find all the broken links
- make a api request to /all.json
- at build time do a regex for what I described above.
- ?
option 2
- figure out how to load markdown files into graphql / gatsby at build time.
- ?
Thoughts?
The current docs sidebar links are changing internal state of the page and setting a hash to match that state.
https://github.com/nodejs/nodejs.dev/blob/6db04d586d6fbcf8924c2996cfcb91f6870b7044/src/pages/docs.tsx#L538-L544
To support page loading, we need to watch the URL for a hash and load the appropriate module into the docs article area.
That's the work I did in #910
I still wonder why you all took this approach (using hashing) vs individual pages. I'd be concerned that SEO would suffer if these 'pages' aren't crawled.
https://nodejs.dev/docs/#temporary_path_for_clearImmediate is broken because there is no current logic for handling page loads with hashes, it only handles click events on navigation to load page in
I'm not sure why either. it was written before I started contributing.
Now that 902 is solved, it looks like the section headers on a page cannot be directly linked to.
Current behavior
On the Timers https://nodejs.dev/docs/#temporary_path_for_timers page, clicking on any of the sub-headers: Timers, Scheduling Timers, or Canceling Timers opens the initial docs page https://nodejs.dev/docs/
however the sidebar navigation now works as expected!
Using hashes for page loads, and then expecting headers/subheaders to deep link isn't going to work too well.
We'd probably need to move away from docs being hashed and have separate URLs built for each. Then sub headings could work properly.
