search

highlightjs / highlight.js

JavaScript syntax highlighter with language auto-detection and zero dependencies.
https://highlightjs.org/
BSD 3-Clause "New" or "Revised" License
23.33k stars 3.52k forks source link

Documentation Page Addition #3241

Closed wolfiex closed 3 years ago

wolfiex commented 3 years ago

A documentation page containing a list of languages not included by default and how to import them would be useful.

This would mean that when searching such a language in the README, a user will be shown how to incorporate it within their code rather than wondering if it is supported or not.

joshgoebel commented 3 years ago

Basic usage is currently well covered both by the README and https://highlightjs.org/usage/. I'm not sure we need to repeat this in the docs (and then deal with having to keep even more places in sync).

Did you find the README insufficient or did you only read the docs and miss the README?

CC @highlightjs/core

wolfiex commented 3 years ago

Ok, Imagine you are a new user. And you wish to find highlighting for a language, in my case fortran2008.

What might you do to find out if it is supported?

I would search the documentation.

Neither the documentation nor the README contain a list of supported languages. It would not occur to me to locate a nested source folder to discover that there is a file for this.

I have found the file: How do I load it?

Although it is losely mentioned in the website For the smallest footprint, load only the languages you need:

It is not obvious that loading custom languages relate to the languages already contained within the library.

What is obvious to someone who wrote the library is far from clear to an end-user just wanting to highlight some code on a well used current language that has been around from the 50s.

joshgoebel commented 3 years ago

Neither the documentation nor the README contain a list of supported languages.

The README does mention this, it's the second major bullet point in the table of contents:

https://github.com/highlightjs/highlight.js#supported-languages

joshgoebel commented 3 years ago

I have added to read the docs:

Plus also restructured things a bit... Does this help?

joshgoebel commented 3 years ago

on a well used current language that has been around from the 50s.

Our "common" build (of ~40 included languages) is based on popularity and usefulness to MOST users, not just age - Fortran just don't qualify in our opinion.

joshgoebel commented 3 years ago

It is not obvious that loading custom languages relate to the languages already contained within the library.

This is also mentioned, with examples: https://github.com/highlightjs/highlight.js#nodejs--require

And: https://github.com/highlightjs/highlight.js#fetch-via-cdn

If you have any specific ideas on making this clearer, please submit a doc PR and we'd be happy to review it. This is not a common support issue though so I think most are users are finding the existing documentation working for them. That said, things can always be improved.

joshgoebel commented 3 years ago

Closing this with the the recent additions/improvements to the docs site (now includes README, supported languages, etc) and https://github.com/highlightjs/highlight.js/commit/50a680877b2777ce2fe30f083037652f9decb5c9