-
-
Notifications
You must be signed in to change notification settings - Fork 157
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
README.md file is getting truncated on GitHub homepage #886
Comments
Personally, I'm not a big fan of concatenating all of the rules together into a monolithic README.md file. It makes it difficult to navigate and parse. Instead, why not have links to the individual rules, like e.g. |
The motivation there makes perfect sense to me, but it has some practical problems. For example, today I wanted to search for the word |
I personally would favor a multiple page, but I defer to the man in charge. :-) I'd suggest using the Table of Contents to get in the vicinity, then clicking on the text of the page above where you want to search, and then use your browser search. |
👍 There's also a small part of me that feels like we should keep the big README.md file, to put just a bit of pressure on GitHub to fix their bug. (It looks like GitHub is no longer recommending people submit bugs to https://github.com/orgs/community/discussions, so I've submitted a support ticket to https://support.github.com/contact/bug-report)
I've found that https://docusaurus.io/docs is usually pretty nice to browse Markdown with, since there's a little table of contents to the right of the page that tells you where in the document you are. It would be pretty easy to setup a basic GitHub Actions workflow that automatically publishes a docusaurus website from the Edit: I just coincidentally saw @Zamiell's face on the Docusaurus repo Looks like you're already really familiar with Docusaurus (I love the Hanabi site)! |
Not likely to be able to do much of anything these days myself, but I may be available to review PRs. I think the GitHub Actions extra docs option might be welcome if someone wanted to go to the trouble of preparing a PR, as long as it could either use our final built README as an input or follow the same build steps from source README files that we currently use. |
Yep. But crucially, notice that with Docusaurus + Algolia, the motivation for having everything on one page is no longer relevant. By just typing "/", you have site-wide instantaneous search capability. So yes, the ultimate solution is to both split up everything into separate rule pages like
Yes I am. :) Thank you. Me and my group have far too many hours in the game. =p
Yes, this is exactly what the Hanabi website does: https://github.com/hanabi/hanabi.github.io/blob/main/.github/workflows/ci.yml#L66-L71 It's trivial to set up. |
Also, if you wanted a better URL, you could create an org called |
Everyone responded here above are contributors. You are all probably familiar with this plugin and it's settings. Besides the horrible load time, the argument of searching is counter productive in my opinion. For almost every rule there is also a massive list of valid and invalid code examples. Aldo those are interesting, I usually want to read the descriptions and find about the options. It cost me so much time to scroll to the next rule, at which point I'm getting to get lost again. If all rules are moved to their own readme's (per ESLint advice), it would be possible to add an TOC to easily link to an rules' description, options, valid and invalid examples. Just my 2 cents. |
|
@gajus would you be willing to reconsider allowing for rules to be in their own markdown files? As can be seen above, it has several limitations being on one page. Many would consider it an improvement to separate it into their own pages, even though subjective in some sense, it has its benefits and clearly this main issue is a big one. Another one is that https://eslint.org/docs/latest/extend/custom-rules#rule-basics says you can specify a
This means that if each rule was on its own page, it could be clicked in editors for users to directly see it. Of course this also works with anchors, but ESLint itself has each role on its own page, see https://eslint.org/docs/latest/rules/ So it would follow their practice as well. Please reconsider @gajus |
There is a PR that might fix this: #940 (thanks @brettz9). Copying the docs from https://github.com/eslint/eslint would also be cool, but I imagine it would be a lot more work than just using something like docusaurus. By the way, GitHub support got back to me about this bug, it looks like it's intended behavior (although I still feel like there could at least be a better warning or something).
|
I just has hardtime to update to v43 as I though My main concern beside the "split documentation" discussion is to make the actual documentation works for users. Is it possible to quick fix those links to the full readme page (and focus on user experience 🙏 ) |
🎉 This issue has been resolved in version 43.2.0 🎉 The release is available on: Your semantic-release bot 📦🚀 |
The README.md file on the GitHub repo homepage (https://github.com/gajus/eslint-plugin-jsdoc) is getting truncated to 512kB.
This cuts off the
valid-types
section.You can test this by looking at the table of contents:
tag-lines
Link worksvalid-types
Link is broken (stays at the top of the README.md)The full README.md can still be viewed by explicitly viewing just the README.md: https://github.com/gajus/eslint-plugin-jsdoc/blob/master/README.md, but that's not something users normally do.
Personally, I feel like this is more of a @github bug than something wrong with your repo (there's should at least be a warning/error message). According to a GitHub staff member, there shouldn't be a README.md limit. But it's been reported to GitHub a few times since 2019 (see bug report in community/community#8222), and it still isn't fixed/confirmed, so 🤷
Want to back this issue? Post a bounty on it! We accept bounties via Bountysource.
The text was updated successfully, but these errors were encountered: