Etherpad v2.1.1 Manual & Documentation

We rely on https://translatewiki.net to handle the translation process for us, so if you’d like to help…​

Translations will be send back to us regularly and will eventually appear in the next release.

As an Etherpad administrator, it is possible to overwrite core messages as well as messages in plugins. These include error messages, labels, and user instructions. Whereas the localization in the source code is in separate files separated by locale, an administrator’s custom localizations are in settings.json under the customLocaleStrings key, with each locale separated by a sub-key underneath.

For example, let’s say you want to change the text on the "New Pad" button on Etherpad’s home page. If you look in locales/en.json (or locales/en-gb.json) you’ll see the key for this text is "index.newPad". You could add the following to settings.json:

If you are ok downloading a prebuilt image from Docker Hub, these are the commands:

If you want to use a personalized settings file, you will have to rebuild your image. All of the following instructions are as a member of the docker group. By default, the Etherpad Docker image is built and run in production mode: no development dependencies are installed, and asset bundling speeds up page load time.

A docker compose file is provided in the project. Please first copy .env.default to .env and adjust the variables to your preference.

Starting dev server:

For production, please create your own docker compose file and change the target property in the build section to production. In addition, change the NODE_ENV in environment to production. For instance:

For plugins, please add them in the build section under ETHERPAD_PLUGINS, for instance:

To run your instance:

And point your browser to http://<YOUR_IP>:<DESIRED_PORT>;

The settings.json.docker available by default allows to control almost every setting via environment variables.

Default: true

Default: true

Default: true

Default: false

Default: "unnamed"

Example: userName=Etherpad%20User

Default: randomly chosen by pad server

Example: userColor=%23ff9900

Default: false

Default: false

Default: en

Example: lang=ar (translates the interface into Arabic)

Default: true Displays pad text from right to left.

Default: 0 Focuses pad at specific line number and places caret at beginning of this line Special note: Is not a URL parameter but instead of a Hash value

The API gives another web application control of the pads. The basic functions are

The API is designed in a way, so you can reuse your existing user system with their permissions, and map it to Etherpad. Means: Your web application still has to do authentication, but you can tell Etherpad via the api, which visitors should get which permissions. This allows Etherpad to fit into any web application and extend it with real-time functionality. You can embed the pads via an iframe into your website.

Take a look at HTTP API client libraries to check if a library in your favorite programming language is available.

Group pads are normal pads, but with the name schema GROUPID$PADNAME. A security manager controls access of them and it’s forbidden for normal pads to include a $ in the name.

Note: The documentation in this section applies to every hook unless the hook-specific documentation says otherwise.

Called from: src/templates/pad.html

Things in context:

nothing

This hook proxies the functionality of jQuery’s $(document).ready event.

Called from: src/static/js/domline.js

Things in context:

This hook is called for elements in the DOM that have the "lineMarkerAttribute" set. You can add elements into this category with the aceRegisterBlockElements hook above. This hook is run BEFORE the numbered and ordered lists logic is applied.

The return value of this hook should have the following structure:

{ preHtml: String, postHtml: String, processedMarker: Boolean }

The preHtml and postHtml values will be added to the HTML display of the element, and if processedMarker is true, the engine won’t try to process it any more.

Called from: src/static/js/domline.js

Things in context:

This hook is called for elements in the DOM that have the "lineMarkerAttribute" set. You can add elements into this category with the aceRegisterBlockElements hook above. This hook is run AFTER the ordered and numbered lists logic is applied.

The return value of this hook should have the following structure:

{ preHtml: String, postHtml: String, processedMarker: Boolean }

The preHtml and postHtml values will be added to the HTML display of the element, and if processedMarker is true, the engine won’t try to process it any more.

Called from: src/static/js/domline.js

Things in context:

This hook is called for any line being processed by the formatting engine, unless the aceDomLineProcessLineAttributes hook from above returned true, in which case this hook is skipped.

The return value of this hook should have the following structure:

{ extraOpenTags: String, extraCloseTags: String, cls: String }

extraOpenTags and extraCloseTags will be added before and after the element in question, and cls will be the new class of the element going forward.

Called from: src/static/js/domline.js

Things in context:

This hook is for right after a node has been fully formatted and written to the page.

Called from: src/static/js/linestylefilter.js

Things in context:

This hook is called during the attribute processing procedure, and should be used to translate key, value pairs into valid HTML classes that can be inserted into the DOM.

The return value for this function should be a list of classes, which will then be parsed into a valid class string.

Called from: src/static/js/linestylefilter.js

Things in context: 1. Attributes - Object of Attributes

This hook is called when attributes are investigated on a line. It is useful if you want to add another attribute type or property type to a pad.

Example:

Called from: src/static/js/linestylefilter.js

Things in context:

This hook is called to apply custom regular expression filters to a set of styles. The one example available is the ep_linkify plugin, which adds internal links. They use it to find the telltale [[ ]] syntax that signifies internal links, and finding that syntax, they add in the internalHref attribute to be later used by the aceCreateDomLine hook (documented above).

Called from: src/static/js/ace.js

Things in context: None

This hook is provided to allow custom CSS files to be loaded. The return value should be an array of resource urls or paths relative to the plugins directory.

Called from: src/static/js/ace.js

Things in context:

This hook is called during the creation of the editor HTML. The array should have lines of HTML added to it, giving the plugin author a chance to add in meta, script, link, and other tags that go into the <head> element of the editor HTML document.

Called from: src/static/js/ace2_inner.js

Things in context:

This hook is made available to edit the edit events that might occur when changes are made. Currently you can change the editor information, some of the meanings of the edit, and so on. You can also make internal changes (internal to your plugin) that use the information provided by the edit event.

Called from: src/static/js/ace2_inner.js

Things in context: None

When aceEditEvent (documented above) finishes processing the event, it scrolls the viewport to make caret visible to the user, but if you don’t want that behavior to happen you can use this hook to register which edit events should not scroll viewport. The return value of this hook should be a list of event names.

Example:

Called from: src/static/js/ace2_inner.js

Things in context: None

The return value of this hook will add elements into the "lineMarkerAttribute" category, making the aceDomLineProcessLineAttributes hook (documented below) call for those elements.

Called from: src/static/js/ace2_inner.js

Things in context:

This hook is for inserting further information into the ace engine, for later use in formatting hooks.

Called from: src/static/js/pad.js

Things in context:

Called from: src/static/js/pad_editbar.js

Things in context:

Can be used to register custom actions to the toolbar.

Usage examples:

Called from: src/static/js/timeslider.js

There doesn’t appear to be any example available of this particular hook being used, but it gets fired after the timeslider is all set up.

Called from: src/static/js/broadcast.js

Things in context:

This hook gets fired both on timeslider load (as timeslider shows a new revision) and when the new revision is showed to a user. There doesn’t appear to be any example available of this particular hook being used.

Called from: src/static/js/pad_userlist.js

Things in context:

This hook is called on the client side whenever a user joins or changes. This can be used to create notifications or an alternate user list.

Called from: src/static/js/chat.js

This hook runs on the client side whenever a chat message is received from the server. It can be used to create different notifications for chat messages. Hook functions can modify the author, authorName, duration, rendered, sticky, text, and timeStr context properties to change how the message is processed. The text and timeStr properties may contain HTML and come pre-sanitized; plugins should be careful to sanitize any added user input to avoid introducing an XSS vulnerability.

Context properties:

Called from: src/static/js/chat.js

This hook runs on the client side whenever the user sends a new chat message. Plugins can mutate the message object to change the message text or add metadata to control how the message will be rendered by the chatNewMessage hook.

Context properties:

Called from: src/static/js/contentcollector.js

Things in context:

This hook is called before the content of a node is collected by the usual methods. The cc object can be used to do a bunch of things that modify the content of the pad. See, for example, the heading1 plugin for etherpad original.

E.g. if you need to apply an attribute to newly inserted characters, call cc.doAttrib(state, "attributeName") which results in an attribute attributeName=true.

If you want to specify also a value, call cc.doAttrib(state, "attributeName::value") which results in an attribute attributeName=value.

Called from: src/static/js/contentcollector.js

Things in context:

This hook is called before the content of an image node is collected by the usual methods. The cc object can be used to do a bunch of things that modify the content of the pad.

Example:

Called from: src/static/js/contentcollector.js

Things in context:

This hook is called after the content of a node is collected by the usual methods. The cc object can be used to do a bunch of things that modify the content of the pad. See, for example, the heading1 plugin for etherpad original.

Called from: src/static/js/collab_client.js

Things in context:

This hook gets called every time the client receives a message of type name. This can most notably be used with the new HTTP API call, "sendClientsMessage", which sends a custom message type to all clients connected to a pad. You can also use this to handle existing types.

collab_client.js has a pretty extensive list of message types, if you want to take a look.

Called from: src/static/js/ace2_inner.js

Things in context:

This hook is provided to allow a plugin to turn DOM node selection into

Called from: src/static/js/ace2_inner.js

Things in context:

This hook is provided to allow a plugin to handle key events. The return value should be true if you have handled the event.

Called from: src/static/js/contentcollector.js

Things in context:

This hook allows you to validate/manipulate the text before it’s sent to the server side. To change the text, either:

Example:

Called from: src/static/js/contentcollector.js

Things in context:

This hook is provided to allow whether the br tag should induce a new magic domline or not. The return value should be either true(break the line) or false.

Called from: src/static/js/linestylefilter.js

Things in context:

This hook is provided to allow whether a given line should be deliniated with multiple authors. Multiple authors in one line cause the creation of magic span lines. This might not suit you and now you can disable it and handle your own deliniation. The return value should be either true(disable) or false.

Called from: src/static/js/ace2_inner.js

Things in context:

This hook is provided to allow author highlight style to be modified. Registered hooks should return 1 if the plugin handles highlighting. If no plugin returns 1, the core will use the default background-based highlighting.

Called from: src/static/js/ace2_inner.js

Things in context:

This hook allows a plugin to react to a cursor or selection change, perhaps to update a UI element based on the style at the cursor location.

Called from: src/node/server.ts

Things in context:

Use this hook to receive the global settings in your plugin.

Called from: src/node/server.ts

Things in context: None

This hook runs before shutdown. Use it to stop timers, close sockets and files, flush buffers, etc. The database is not available while this hook is running. The shutdown function must not block for long because there is a short timeout before the process is forcibly terminated.

The shutdown function must return a Promise, which must resolve to undefined. Returning callback(value) will return a Promise that is resolved to value.

Example:

Called from: src/static/js/pluginfw/installer.js

Things in context:

If this hook returns an error, the callback to the uninstall function gets an error as well. This mostly seems useful for handling additional features added in based on the installation of other plugins, which is pretty cool!

Called from: src/static/js/pluginfw/installer.js

Things in context:

If this hook returns an error, the callback to the install function gets an error, too. This seems useful for adding in features when a particular plugin is installed.

Called from: src/static/js/pluginfw/plugins.js

Run during startup after the named plugin is initialized.

Context properties:

Called from: src/node/hooks/express.js

Called during server startup just before the express-session middleware is added to the Express Application object. Use this hook to add route handlers or middleware that executes before express-session state is created and authentication is performed. This is useful for creating public endpoints that don’t spam the database with new express-session records or trigger authentication.

WARNING: All handlers registered during this hook run before the built-in authentication checks, so any handled endpoints will be public unless the handler itself authenticates the user.

Context properties:

Example:

Called from: src/node/hooks/express.js

Called during server startup just after the express-session middleware is added to the Express Application object. Use this hook to add route handlers or middleware that executes after express-session state is created and authentication is performed.

Context properties:

Called from: src/node/hooks/express.js

Identical to the expressConfigure hook (the two run in parallel with each other) except this hook’s context includes the HTTP Server object.

Context properties:

Called from: src/node/hooks/express.js

Things in context: Nothing

This hook is called when the HTTP server is closing, which happens during shutdown (see the shutdown hook) and when the server restarts (e.g., when a plugin is installed via the /admin/plugins page). The HTTP server may or may not already be closed when this hook executes.

Example:

Called from: src/node/eejs/index.js

Things in context:

This hook gets called upon the rendering of an ejs template block. For any specific kind of block, you can change how that block gets rendered by modifying the content object passed in.

Available blocks in pad.html are:

timeslider.html blocks:

index.html blocks:

Called from: src/node/hooks/express/specialpages.js

Things in context:

Here you can add custom toolbar items that will be available in the toolbar config in settings.json. For more about the toolbar controller see the API section.

Usage examples:

Called from: src/node/db/SecurityManager.js

Things in context:

This hook gets called when the access to the concrete pad is being checked. Return false to deny access.

Called from src/node/db/AuthorManager.js

Called when looking up (or creating) the author ID for a user, except for author IDs obtained via the HTTP API. Registered hook functions are called until one returns a non-undefined value. If a truthy value is returned by a hook function, it is used as the user’s author ID. Otherwise, the value of the dbKey context property is used to look up the author ID. If there is no such author ID at that key, a new author ID is generated and associated with that key.

Context properties:

Example:

Called from: src/node/db/Pad.js

Called when a new pad is created.

Context properties:

Called from src/node/db/Pad.js

Called to obtain a pad’s initial content, unless the pad is being created with specific content. The return value is ignored; to change the content, modify the content context property.

This hook is run asynchronously. All registered hook functions are run concurrently (via Promise.all()), so be careful to avoid race conditions when reading and modifying the context properties.

Context properties:

Called from: src/node/db/PadManager.js

Called when a pad is loaded, including after new pad creation.

Context properties:

Called from: src/node/db/Pad.js

Called when an existing pad is updated.

Context properties:

Called from: src/node/db/Pad.js

Called when a pad is copied so that plugins can copy plugin-specific database records or perform some other plugin-specific initialization.

Order of events when a pad is copied:

Context properties:

Usage examples:

Called from: src/node/db/Pad.js

Called when an existing pad is removed/deleted. Plugins should use this to clean up any plugin-specific pad records from the database.

Context properties:

Usage examples:

Called from: src/node/db/Pad.js

Called when a consistency check is run on a pad, after the core checks have completed successfully. An exception should be thrown if the pad is faulty in some way.

Context properties:

Called from: src/node/hooks/express/socketio.js

Things in context:

I have no idea what this is useful for, someone else will have to add this description.

Called from: src/node/hooks/express/webaccess.js

Called for each HTTP request before any authentication checks are performed. The registered preAuthorize hook functions are called one at a time until one explicitly grants or denies the request by returning true or false, respectively. If none of the hook functions return anything, the access decision is deferred to the normal authentication and authorization checks.

Example uses:

Return values:

Context properties:

Example:

Called from: src/node/hooks/express/webaccess.js

Things in context:

This hook is called to handle authorization. It is especially useful for controlling access to specific paths.

A plugin’s authorize function is only called if all of the following are true:

Note that the authorize hook cannot grant access to /admin pages. If admin access is desired, the is_admin user setting must be set to true. This can be set in the settings file or by the authenticate hook.

You can pass the following values to the provided callback:

Example:

Called from: src/node/hooks/express/webaccess.js

Things in context:

This hook is called to handle authentication.

Plugins that supply an authenticate function should probably also supply an authnFailure function unless falling back to HTTP basic authentication is appropriate upon authentication failure.

This hook is only called if either the requireAuthentication setting is true or the request is for an /admin page.

Calling the provided callback with [true] or [false] will cause authentication to succeed or fail, respectively. Calling the callback with [] or undefined will defer the authentication decision to the next authentication plugin (if any, otherwise fall back to HTTP basic authentication).

If you wish to provide a mix of restricted and anonymous access (e.g., some pads are private, others are public), you can "authenticate" (as a guest account) users that have not yet logged in, and rely on other hooks (e.g., authorize, onAccessCheck, handleMessageSecurity) to authorize specific privileged actions.

If authentication is successful, the authenticate function MUST set context.req.session.user to the user’s settings object. The username property of this object should be set to the user’s username. The settings object should come from global settings (context.users[username]).

Example:

Called from: src/node/hooks/express/webaccess.js

Things in context:

DEPRECATED: Use authnFailure or authzFailure instead.

This hook is called to handle an authentication or authorization failure.

Plugins that supply an authenticate function should probably also supply an authnFailure function unless falling back to HTTP basic authentication is appropriate upon authentication failure.

A plugin’s authFailure function is only called if all of the following are true:

Calling the provided callback with [true] tells Etherpad that the failure was handled and no further error handling is required. Calling the callback with [] or undefined defers error handling to the next authFailure plugin (if any, otherwise fall back to HTTP basic authentication for an authentication failure or a generic 403 page for an authorization failure).

Example:

Called from: src/node/hooks/express/webaccess.js

Things in context:

This hook is called to handle a pre-authentication authorization failure.

A plugin’s preAuthzFailure function is only called if the pre-authentication authorization failure was not already handled by a preAuthzFailure function from another plugin.

Calling the provided callback with [true] tells Etherpad that the failure was handled and no further error handling is required. Calling the callback with [] or undefined defers error handling to a preAuthzFailure function from another plugin (if any, otherwise fall back to a generic 403 error page).

Example:

Called from: src/node/hooks/express/webaccess.js

Things in context:

This hook is called to handle an authentication failure.

Plugins that supply an authenticate function should probably also supply an authnFailure function unless falling back to HTTP basic authentication is appropriate upon authentication failure.

A plugin’s authnFailure function is only called if the authentication failure was not already handled by an authnFailure function from another plugin.

Calling the provided callback with [true] tells Etherpad that the failure was handled and no further error handling is required. Calling the callback with [] or undefined defers error handling to an authnFailure function from another plugin (if any, otherwise fall back to the deprecated authFailure hook).

Example:

Called from: src/node/hooks/express/webaccess.js

Things in context:

This hook is called to handle a post-authentication authorization failure.

A plugin’s authzFailure function is only called if the authorization failure was not already handled by an authzFailure function from another plugin.

Calling the provided callback with [true] tells Etherpad that the failure was handled and no further error handling is required. Calling the callback with [] or undefined defers error handling to an authzFailure function from another plugin (if any, otherwise fall back to the deprecated authFailure hook).

Example:

Called from: src/node/handler/PadMessageHandler.js

This hook allows plugins to drop or modify incoming socket.io messages from clients, before Etherpad processes them. If any hook function returns null then the message will not be subject to further processing.

Context properties:

Example:

Called from: src/node/handler/PadMessageHandler.js

Called for each incoming message from a client. Allows plugins to grant temporary write access to a pad.

Supported return values:

Context properties:

Example:

Called from: src/node/handler/PadMessageHandler.js

Things in context:

This hook is called after a client connects but before the initial configuration is sent to the client. Plugins can use this hook to manipulate the configuration. (Example: Add a tracking ID for an external analytics tool that is used client-side.)

You can manipulate clientVars in two different ways: * Return an object. The object will be merged into clientVars via Object.assign(), so any keys that already exist in clientVars will be overwritten by the values in the returned object. * Modify context.clientVars. Beware: Other plugins might also be reading or manipulating the same context.clientVars object. To avoid race conditions, you are encouraged to return an object rather than modify context.clientVars.

If needed, you can access the user’s account information (if authenticated) via context.socket.client.request.session.user.

Examples:

Called from: src/node/utils/ExportHtml.js

This hook will allow a plug-in developer to re-write each line when exporting to HTML.

Context properties:

Example:

Called from: src/node/utils/ExportHtml.js

Things in context:

This hook will allow a plug-in developer to include additional HTML content in the body of the exported HTML.

Example:

Called from: src/node/utils/ExportHtml.js

Things in context:

This hook will allow a plug-in developer to append Styles to the Exported HTML.

Example:

Called from: src/static/js/linestylefilter.js

This hook is called when attributes are investigated on a line. It is useful if you want to add another attribute type or property type to a pad.

An attributes object is passed to the aceAttribClasses hook functions instead of the usual context object. A hook function can either modify this object directly or provide an object whose properties will be assigned to the attributes object.

Example:

Called from src/node/handler/ExportHandler.js

Things in context:

This hook will allow a plug-in developer to modify the file name of an exported pad. This is useful if you want to export a pad under another name and/or hide the padId under export. Note that the doctype or file extension cannot be modified for security reasons.

Example:

Called from src/node/utils/ExportHtml.js

Things in context:

This hook will allow a plug-in developer to include more properties and attributes to support during HTML Export. If tags are stored as ['color', 'red'] on the attribute pool, use exportHtmlAdditionalTagsWithData instead. An Array should be returned.

Example:

Called from src/node/utils/ExportHtml.js

Things in context:

Identical to exportHtmlAdditionalTags, but for tags that are stored with a specific value (not simply true) on the attribute pool. For example ['color', 'red'], instead of ['bold', true]. This hook will allow a plug-in developer to include more properties and attributes to support during HTML Export. An Array of arrays should be returned. The exported HTML will contain tags like <span data-color="red"> for the content where attributes are ['color', 'red'].

Example:

Called from src/node/utils/ExportEtherpad.js and src/node/utils/ImportEtherpad.js.

Called when exporting to an .etherpad file or when importing from an .etherpad file. The hook function should return prefixes for pad-specific records that should be included in the export/import. On export, all ${prefix}:${padId} and ${prefix}:${padId}:* records are included in the generated .etherpad file. On import, all ${prefix}:${padId} and ${prefix}:${padId}:* records are loaded into the database.

Context properties: None.

Example:

Called from src/node/utils/ExportEtherpad.js.

Called when exporting to an .etherpad file.

Context properties:

Called from src/node/utils/ImportEtherpad.js.

Called when importing from an .etherpad file.

Context properties:

Called from: src/node/handler/ImportHandler.js

Called when a user submits a document for import, before the document is converted to HTML. The hook function should return a truthy value if the hook function elected to convert the document to HTML.

Context properties:

Example:

Called from: src/node/handler/PadMessageHandler.js

Called after users have been notified that a new user has joined the pad.

Context properties:

Example:

Called from: src/node/handler/PadMessageHandler.js

Called when a user disconnects from a pad. This is useful if you want to perform certain actions after a pad has been edited.

Context properties:

Example:

Called from: src/node/handler/PadMessageHandler.js

Called when a user (or plugin) generates a new chat message, just before it is saved to the pad and relayed to all connected users.

Context properties:

This function replaces a range (from start to end) with text.

Returns the rep object.

Sets an attribute on current range. Example: `call.editorInfo.ace_setAttributeOnSelection("turkey::balls", true); // turkey is the attribute here, balls is the value Notes: to remove the attribute pass enabled as false

Returns a boolean if an attribute exists on a selected range. prevChar value should be true if you want to get the previous Character attribute instead of the current selection for example if the caret is at position 0,1 (after first character) it’s probable you want the attributes on the character at 0,0 The attribute should be the string name of the attribute applied to the selection IE subscript Example usage: Apply the activeButton Class to a button if an attribute is on a highlighted/selected caret position or range. Example var isItThere = documentAttributeManager.getAttributeOnSelection("turkey::balls", true);

See the ep_subscript plugin for an example of this function in action. Notes: Does not work on first or last character of a line. Suffers from a race condition if called with aceEditEvent.

Returns an info object about the author. Object key = author_id and info includes author’s bg color value. Use to define your own authorship.

This function replaces a range (from [x1,y1] to [x2,y2]) with newText.

This function replaces a range (from y1 to y2) with newText.

If you delete a line, calling this method will fix the line numbering.

Forces a return key at the current caret position.

Returns true if your passed element is registered as a block element

Returns the line’s html list type.

Returns X position of the caret.

Returns Y position of the caret.

Returns the Y offset starting from [x=0,y=0]

A changeset describes the difference between two revisions of a document. When a user edits a pad, the browser generates and sends a changeset to the server, which relays it to the other users and saves a copy (so that every past revision is accessible).

A transmitted changeset looks like this:

Changesets do not include any attribute key–value pairs. Instead, they use numeric identifiers that reference attributes kept in an attribute pool. This attribute interning reduces the transmission overhead of attributes that are used many times.

There is one attribute pool per pad, and it includes every current and historical attribute used in the pad.

Detailed information about the changesets & Easysync protocol:

require("ep_etherpad-lite/static/js/plugingfw/plugins").update() will use npm to list all installed modules and read their ep.json files, registering the contained hooks. A hook registration is a pair of a hook name and a function reference (filename for require() plus function name)

require("ep_etherpad-lite/static/js/plugingfw/hooks").callAll("hook_name", {argname:value}) will call all hook functions registered for hook_name with {argname:value}.

?

Returns: {Button}

Example:

You can also create buttons with text:

Returns: {SelectButton}

Shows the dropdown div.popup whose id equals dropdown.

Register a handler for a specific command. Commands are fired if the corresponding button is clicked or the corresponding select is changed.

Creates an ace callstack and calls the callback with an ace instance (and a toolbar item, if applicable): callback(cmd, ace, item).

Example:

Ties a div.popup where id equals dropdown to a command fired by clicking a button.

Triggers a command (optionally with some internal representation of the toolbar item that triggered it).

Ideally a plugin has the following folder structure:

If your plugin includes client-side hooks, put them in static/js/. If you’re adding in CSS or image files, you should put those files in static/css/ `and `static/image/, respectively, and templates go into templates/. Translations go into locales/. Tests go in static/tests/backend/specs/ and static/tests/frontend/specs/.

A Standard directory structure like this makes it easier to navigate through your code. That said, do note, that this is not actually required to make your plugin run. If you want to make use of our i18n system, you need to put your translations into locales/, though, in order to have them integrated. (See "Localization" for more info on how to localize your plugin.)

Your plugin definition goes into ep.json. In this file you register your hook functions, indicate the parts of your plugin and the order of execution. (A documentation of all available events to hook into can be found in chapter Server-side hooks.)

A hook function registration maps a hook name to a hook function specification. The hook function specification looks like ep_example/file.js:functionName. It consists of two parts separated by a colon: a module name to require() and the name of a function exported by the named module. See module.exports for how to export a function.

For the module name you can omit the .js suffix, and if the file is index.js you can use just the directory name. You can also omit the module name entirely, in which case it defaults to the plugin name (e.g., ep_example).

You can also omit the function name. If you do, Etherpad will look for an exported function whose name matches the name of the hook (e.g., authenticate).

If either the module name or the function name is omitted (or both), the colon may also be omitted unless the provided module name contains a colon. (So if the module name is C:\foo.js then the hook function specification with the function name omitted would be "C:\\foo.js:".)

Examples: Suppose the plugin name is ep_example. All of the following are equivalent, and will cause the authorize hook to call the exports.authorize function in index.js from the ep_example plugin:

Your plugin must also contain a package definition file, called package.json, in the project root - this file contains various metadata relevant to your plugin, such as the name and version number, author, project hompage, contributors, a short description, etc. If you publish your plugin on npm, these metadata are used for package search etc., but it’s necessary for Etherpad plugins, even if you don’t publish your plugin.

If your plugin adds or modifies the front end HTML (e.g. adding buttons or changing their functions), you should put the necessary HTML code for such operations in templates/, in files of type ".ejs", since Etherpad uses EJS for HTML templating. See the following link for more information about EJS: https://github.com/visionmedia/ejs.

Etherpad allows you to easily create front-end tests for plugins.