Skip to content

Latest commit

 

History

History
82 lines (51 loc) · 4.27 KB

CONTRIBUTING.md

File metadata and controls

82 lines (51 loc) · 4.27 KB
Raw

Contributing

Note: This guide is a work in progress. Feel free to submit an issue if anything is confusing or unclear.

How linkify works

TODO: Insert diagram here

Linkify uses a two stage lexicographical analysis to detect patterns in plain text.

The first stage, called the scanner, takes the input string and generates encompassing tokens that aggregate different types of components like domain names and TLDs. For example, substings like http: or com are converted into tokens named PROTOCOL and TLD, respectively.

The second stage, the parser, takes this array of tokens and aggregates them into complete entities that are either become links or do not. For example, the tokens PROTOCOL, SLASH, SLASH, DOMAIN, TLD (appearing in that order) are grouped into a URL entity. These groups are called multitokens.

A multi token is either a link or not a link. Basic linkify comes with these multitokens

  • TEXT is plain text (that contains no linkable entities)
  • NL represents a single newline character
  • EMAIL email address
  • URL

The latter two are converted to links. NL is in some cases converted to a <br> HTML tag.

You can use the Token class system to create plugins.

Style

  • ES6 Syntax (except tests for now)
  • Hard tabs with a width of 4 characters

As usualy, try to keep it consistent with what's already there.

Development

Setup

  1. Install the latest version of Node.js
  2. Install the gulp.js build system from the Terminal
    • npm install -g gulp

Building

Linkify is built and tested in the command line. Build tasks have the following format.

gulp <task>

Here are the primary build tasks used for development. See gulpfile.js for the complete list.

  • build transpiles ES6 to ES5 (via Babel) from src/ into lib/. The lib folder will be published to NPM. Also generates browser-ready scripts (globals and AMD) into the build/ folder.
  • dist copies and compresses the contents of build/ into dist/. The contents of the dist folder will be published to Bower.
  • default (run gulp without arguments) runs build and begins watching files for changes (rebuilding when they do)

Running tests

Here are the tools used for testing linkify:

  • Mocha is our primary test case framework
  • ESLint for code linting
  • Istanbul for code coverage analysis
  • Karma is our browser test runner
  • Sauce Labs for cross-browser testing

These are all configured to run on gulp. Tasks mocha and eslint are the most basic you can run. Other tasks include:

  • test transpiles the code and runs ESLint and Mocha
  • coverage runs Istanbul code coverage on the Mocha tests
  • Karma has a number of tasks that allow you to run Mocha tests on different browsers (via Browserify)
    • karma runs tests on the PhantomJS headless browser
    • karma-chrome runs tests on Google Chrome
    • karma-ci (or test-ci) runs Sauce Labs cross-browser tests (Sauce Labs environment configuration required)

Building plugins

Caution: The plugin development API is in its very early stages and only supports very basic plugins. Updated features, APIs, and docs are in the works.

Check out the sample Hashtag plugin for an idea of how plugins are made. You have access to all the previously described tokens from the linkify variable. And should be able to extend them as necessary.

If you decide that your plugin can be used by many people, you can add them to src/linkify/plugins/. Make sure you also create build templates for your plugin inside templates/linkify/plugins/. Follow the format of the existing files.

Any plugin you add to src/linkify/plugins/ will automatically be added to the build system.