README.md file is getting truncated on GitHub homepage

[aloisklink]

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 works
• valid-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 https://github.com/github/feedback/discussions/8222), and it still isn't fixed/confirmed, so :shrug:

[Zamiell]

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. typescript-eslint does?

[brettz9]

@Zamiell : Others have expressed this also, but @gajus was not favorable to such changes (preferring to have a single document allowing for browser search).

[Zamiell]

The motivation there makes perfect sense to me, but it has some practical problems.

For example, today I wanted to search for the word context to see if a particular rule supported it as an option. So I typed ctrl + f and typed in context, and it warped me to the next match, as you would expect. However, because there is no context of where I am in the document, it's impossible to know if this current context match was in the rule that I cared about or was in some other rule. Because each rule is a huge wall of text, I'm completely lost contextually for where I am in the document, making this extremely simple task a nightmare.

[brettz9]

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.

[aloisklink]

but I defer to the man in charge

:+1:

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)

Because each rule is a huge wall of text, I'm completely lost contextually for where I am in the document, making this extremely simple task a nightmare.

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 README.md to the gh-pages branch, at something like https://gajus.github.io/eslint-plugin-jsdoc, no idea if that's worth the effort though.

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)!

[brettz9]

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.

[Zamiell]

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.

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 typescript-eslint, and also transition to Docusaurus so that everything looks pretty and you have easy site-wide search.

Edit: I just coincidentally saw https://github.com/facebook/docusaurus/discussions/7826#discussioncomment-3224653 Looks like you're already really familiar with Docusaurus (I love the Hanabi site)!

Yes I am. :) Thank you. Me and my group have far too many hours in the game. =p

It would be pretty easy to setup a basic GitHub Actions workflow that automatically publishes a docusaurus website from the README.md to the gh-pages branch, at something like https://gajus.github.io/eslint-plugin-jsdoc, no idea if that's worth the effort though.

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.

[Zamiell]

Also, if you wanted a better URL, you could create an org called eslint-plugin-jsdoc, and that would net you eslint-plugin-jsdoc.github.io, which is a little better.

[jerone]

Everyone responded here above are contributors. You are all probably familiar with this plugin and it's settings. From an user perspective, that comes here for installation and once in a while after an update, I can say this readme is very overwhelming.

Besides the horrible load time, the argument of searching is counter productive in my opinion. GitHub has it's own search functionality, which is easy to use. Plus, when searching on the readme, because of the long rule explanations, I have no idea if I already skipped to the next rule or not. If search engine visibility (Google, etc..) is so important, then just create an github.io page.

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.

[jespertheend]

tag-lines from OP now also doesn't work anymore. I thought it simply wasn't documented until I stumbled upon this.

[thernstig]

@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 url string:

url (string) specifies the URL at which the full documentation can be accessed (enabling code editors to provide a helpful link on highlighted rule violations)

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

[aloisklink]

There is a PR that might fix this: https://github.com/gajus/eslint-plugin-jsdoc/pull/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).

We do have some file size limits, which are described here.

https://docs.github.com/en/repositories/creating-and-managing-repositories/about-repositories#text-limits

"Text files over 512 KB are always displayed as plain text. Code is not syntax highlighted, and prose files are not converted to HTML (such as Markdown, AsciiDoc, etc.).

Text files over 5 MB are only available through their raw URLs, which are served through raw.githubusercontent.com; for example, https://raw.githubusercontent.com/octocat/Spoon-Knife/master/index.html. Click the Raw button to get the raw URL for a file."

These are in place for performance reasons.

[yvele]

I just has hardtime to update to v43 as I though tag-lines was not documented. Thanks to @aloisklink I managed to view the documentation on the full README file: https://github.com/gajus/eslint-plugin-jsdoc/blob/main/README.md#tag-lines

My main concern beside the "split documentation" discussion is to make the actual documentation works for users. In the readme all those rule documentation are missing:

Is it possible to quick fix those links to the full readme page (and focus on user experience 🙏 )

[github-actions[bot]]

:tada: This issue has been resolved in version 43.2.0 :tada:

The release is available on:

• GitHub release
• npm package (@latest dist-tag)

Your semantic-release bot :package::rocket: