chore(docs) Explain the 1st party vs 3rd party situation a little bet…

…ter (#2823)

Co-authored-by: Josh Goebel <[email protected]>

docs/language-contribution.rst

@@ -1,13 +1,37 @@
 Language contributor checklist
 ==============================
 
-1. Read ``extra/3RD_PARTY_QUICK_START.md``
-------------------------------------------
+1. Know that you are creating a 3rd party grammar
+-------------------------------------------------
 
-It contains rough high-level steps for creating a 3rd party language grammar for Highlight.js.
+*Sadly, due to lack of maintainer time we no longer merge new languages grammars
+into the core library.* Instead, the project works by encouraging 3rd party
+language grammar development by willing contributors ready to help and maintain
+them. We're also happy to host those 3rd party language grammars at the
+``highlightjs`` GitHub organization. Or you're welcome to host yourself - we're
+always happy to link to to new language grammars.
 
+We also make it easy to build, maintain, and distribute 3rd party grammar
+modules so that Highlight.js can always be easily extended with new languages.
+Using a 3rd party language (for end users) is often as simple as just adding a
+single line of code to their JavaScript or build system.
 
-2. Create a language grammar definition file
+We'd love to have your grammar as a 3rd party language module if you'd be
+willing to maintain it over time.  It's easy to develop and publish a 3rd party
+language module.  If you already started work in the main source tree - it's
+trivial to convert your existing work into a 3rd party module. (you pretty much
+just move your files into a new project folder)
+
+
+2. Read extra/3RD_PARTY_QUICK_START.md
+--------------------------------------
+
+Next, read ``extra/3RD_PARTY_QUICK_START.md``.  This should provide you with a
+very high-level overview of the steps for creating a third-party language
+grammar for Highlight.js.
+
+
+3. Create a language grammar definition file
 --------------------------------------------
 
 The file defines a function accepting a reference to the library and returning a language object.
@@ -25,10 +49,12 @@ process and details differ for different build targets.
     }
   }
 
-The name of the file is used as a short language identifier and should be usable as a class name in HTML and CSS.
+The name of the file is used as a short language identifier and should be usable
+as a class name in HTML and CSS.  Typically you'll place this file in your
+new grammar repository under ``my_new_grammar/src/languages/``.
 
 
-3. Add language metadata
+4. Add language metadata
 ----------------------------
 
 At the top of the file there is a specially formatted comment with meta data processed by a build system.
@@ -56,7 +82,7 @@ The build system just makes sure that they will be in the final package in
 The meaning of the other headers should be pretty obvious.
 
 
-4. Create a code example
+5. Create a code example
 ------------------------
 
 The code example is used both to test language detection and for the demo page
@@ -66,7 +92,7 @@ Take inspiration from other languages in ``test/detect/`` and read
 :ref:`testing instructions <basic-testing>` for more details.
 
 
-5. Write a class reference if your class uses custom classes
+6. Write a class reference if your class uses custom classes
 ------------------------------------------------------------
 
 A class reference document should typically be placed at the root of your
@@ -79,14 +105,14 @@ are not going to support your custom classes and you should likely also
 distribute your own custom theme.
 
 
-6. Request a repository at the ``highlightjs`` organization
+7. Request a repository at the ``highlightjs`` organization
 ----------------------------------------------------------
 
 *This is optional.*  Of course you are free to host your repository anywhere
 you would like.
 
 
-7. Create a pull request
+8. Create a pull request
 ------------------------
 
 Submit a PR to add your language to `SUPPORTED_LANGUAGES.md`.