-
Notifications
You must be signed in to change notification settings - Fork 6
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
feat: legacy html generator #55
Conversation
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
Correct, it indexes the LTS version. That's a good point. @micheleriva, what are the alternatives here? Can we make it for API doc generation so the whole database can be built locally based on metadata we ingest? i.e., is it a static database stored in a static file and loaded by the Orama client during bootstrap (client side) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
lgtm
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
@ovflowd sorry for my late reply. Yes, we can definitely do this. Let me just point out that the search results may slightly differ from Orama Cloud (more performant, more accurate results) and Orama OSS. I hope that's not a dealbreaker. |
I think that's a fair trade-off, at least within directly the Node.js API docs pages. Are there docs out there on how we can use this? |
We have our docs at https://docs.orama.com/open-source, and you would probably need to use that plugin: https://docs.orama.com/open-source/plugins/plugin-data-persistence. We can give you support probably starting next week or so to write down a reference architecture/implementation 🙏 |
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as outdated.
This comment was marked as outdated.
508950d
to
f3bc34e
Compare
This comment was marked as resolved.
This comment was marked as resolved.
f3bc34e
to
147a349
Compare
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
Co-authored-by: Brian Muenzenmeyer <brian.muenzenmeyer@gmail.com>
f9f7b64
to
6f57517
Compare
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
@targos Ive updated the code so that the metadata generation is like on the current API docs. I will update the tests of this PR later. |
@nodejs/web-infra @canerakdas one last code review? 🙏 Also, @targos let me know if you find any other inconsistency 🙏 |
FYI I'merging this for the time being, to unblock @flakey5; Happy to iterate on following PRs. @AugustinMauroy I would love if you could help with some extra tests now that the logic is full I believe you have more material to test! 😃 If you want you can also use the experimental snapshot feature for snapshot tests of html output based on mock markdown sources that mock numerous different pieces of our metadata and content (code blocks, switchable code blocks, all sort of yaml metadata etc) I think that working on said tests would be awesome for you to get familiar with the nitty gritty of our API docs stuff ;D |
@targos let me know if perchance I also missed anything. @flakey5 is working on the json generator (legacy-json and legacy-json-all) to generate matching json output for the current api docs :) After that I believe we would be able to start the process of replacing the current tooling with this one on nodejs/node |
Description
This PR introduces the Legacy HTML generator, which aims to generate an almost 1:1 replica of the existing https://nodejs.org/api/ documentation.
This PR introduces the fully-fledged
legacy-HTML
generator, with all the related utilities and tools to make complete API docs in HTML.Diversions from the original version:
nodejs/node/doc/api/index.md
Things to be done:
None. We're feature complete!
Future generators
json
generator, being able to generate.json
files for API docsreact
generator, the redesign of API docs generator.Validation
Clone, run
npm install
, then run the command against Node.js API docs, for example:npx api-docs-tooling -i "/path/to/node/doc/api/*.md" -t legacy-html -o /tmp/out
You can just open the desired files on your browser.
Preview
This is deployed temporarily on Netlify (not auto deployed on commits, I'm manually deploying it): https://node-api-docs-legacy-preview.netlify.app/
Related Issues
Closes #15