From fb007ffd4641c423ca7bfea8d1dbbe1a472ff234 Mon Sep 17 00:00:00 2001 From: Brad Chamberlain <bradcray@users.noreply.github.com> Date: Fri, 13 Nov 2020 09:12:04 -0800 Subject: [PATCH] chore(docs) Explain the 1st party vs 3rd party situation a little better (#2823) Co-authored-by: Josh Goebel <me@joshgoebel.com> --- docs/language-contribution.rst | 46 ++++++++++++++++++++++++++-------- 1 file changed, 36 insertions(+), 10 deletions(-) diff --git a/docs/language-contribution.rst b/docs/language-contribution.rst index f492becb4e..1e2de0a9f5 100644 --- a/docs/language-contribution.rst +++ b/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`.