add docs

Author: joshgoebel

extra/.keep

@@ -0,0 +1,70 @@
+*This is a work in progress.  PRs to improve these docs (or the process) would be welcome.*
+
+## Getting Started
+
+So you'd like to create and share you're own language for Highlight.js.  That's awesome.
+
+Take a look at some of the real-life examples first:
+
+- https://github.com/highlightjs/highlightjs-cypher
+- https://github.com/highlightjs/highlightjs-robots-txt
+
+Basically:
+
+- Checkout highlight-js from github...
+- 3rd party languages are placed into the `extra` directory
+
+So if you had a `xzy` language you'd create an `extra/xyz` folder, and that would be your language module. All paths below are relative to that.
+
+- Put your language file in `src/languages/name.js`.
+- Add detect tests in `test/detect/`.
+- Add markup tests in `test/markup/`.
+- Perhaps add a `package.json` for Node.
+- Add a nice `README`.
+- Don't forget to add a `LICENSE`.
+
+
+## Testing
+
+To test (detect and markup tests), just build highlight.js and test it.  Your tests should be automatically run with the suite:
+
+```
+node ./tools/build.js -t node
+npm run test
+```
+
+If you can't get the auto-detect tests passing you should simply turn off auto-detection for your language in it's definition with `disableAutodetect: true`.  Auto-detection is hard.
+
+
+## Packaging
+
+Users will expect your package to include a minified CDN distributable in your `dist` folder. This should allow them to add the module to their website with only a single `<script>` tag.
+
+Luckily, the highlight.js CDN build process will build this file for you automatically.  You can simply commit it to your repo, and done.
+
+```
+node ./tools/build.js -t cdn
+
+...
+Building extra/highlightjs-xyz/dist/xyz.min.js.
+...
+```
+
+
+## Publishing
+
+We're happy to host 3rd party module repos inside the `highlightjs` organization on GitHub.  Just file an issue and request a repository.
+
+Publish it to NPM also if you'd like. This will make it much easier for anyone using Node to use it.
+
+When your language module is ready create a PR that adds it to the `README.md` file in the list of languages.
+
+
+## The Future
+
+More work could be done on:
+
+- Allowing you to ONLY run your own tests, not the whole suite.
+- Allowing you to maintain a 3rd party module WITHOUT it being inside of a `highlight-js` checkout (this requires discussion though)
+- Simply make some easier tools or scripts to simply the existing process.
+- Improving these docs