Added docs as asciidoctor with cross platform support. (#5733)

* Added docs as asciidoctor with cross platform support.

* Fixed release script with new doc building mechanism.

Makefile

@@ -1,32 +0,0 @@
-doc_sources = $(wildcard doc/*/*.md) $(wildcard doc/*.md)
-outdoc_files = $(addprefix out/,$(doc_sources:.md=.html))
-
-docassets = $(addprefix out/,$(wildcard doc/assets/*))
-
-VERSION = $(shell node -e "console.log( require('./src/package.json').version )")
-UNAME := $(shell uname -s)
-
-ensure_marked_is_installed:
-	set -eu; \
-	hash npm; \
-	if [ $(shell npm list --prefix src/bin/doc >/dev/null 2>/dev/null; echo $$?) -ne "0" ]; then \
-		npm ci --prefix=src/bin/doc; \
-	fi
-
-docs: ensure_marked_is_installed $(outdoc_files) $(docassets)
-
-out/doc/assets/%: doc/assets/%
-	mkdir -p $(@D)
-	cp $< $@
-
-out/doc/%.html: doc/%.md
-	mkdir -p $(@D)
-	node src/bin/doc/generate.js --format=html --template=doc/template.html $< > $@
-ifeq ($(UNAME),Darwin)
-	sed -i '' 's/__VERSION__/${VERSION}/' $@
-else
-	sed -i 's/__VERSION__/${VERSION}/' $@
-endif
-
-clean:
-	rm -rf out/

doc/api/api.adoc

@@ -0,0 +1,19 @@
+include::./embed_parameters.adoc[]
+
+include::./http_api.adoc[]
+
+include::./hooks_overview.adoc[]
+
+include::./hooks_client-side.adoc[]
+
+include::./hooks_server-side.adoc[]
+
+include::./editorInfo.adoc[]
+
+include::./changeset_library.adoc[]
+
+include::./pluginfw.adoc[]
+
+include::./toolbar.adoc[]
+
+include::./editbar.adoc[]

doc/api/api.md

@@ -1,10 +0,0 @@
-@include embed_parameters
-@include http_api
-@include hooks_overview
-@include hooks_client-side
-@include hooks_server-side
-@include editorInfo
-@include changeset_library
-@include pluginfw
-@include toolbar
-@include editbar

doc/api/changeset_library.adoc

@@ -1,14 +1,15 @@
-# Changeset Library
+== Changeset Library
 
-The [changeset
-library](https://github.com/ether/etherpad-lite/blob/develop/src/static/js/Changeset.js)
+The https://github.com/ether/etherpad-lite/blob/develop/src/static/js/Changeset.js[changeset
+library]
 provides tools to create, read, and apply changesets.
 
-## Changeset
+=== Changeset
 
-```javascript
+[source,javascript]
+----
 const Changeset = require('ep_etherpad-lite/static/js/Changeset');
-```
+----
 
 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,
@@ -17,28 +18,29 @@ is accessible).
 
 A transmitted changeset looks like this:
 
-```
+[source]
+----
 'Z:z>1|2=m=b*0|1+1$\n'
-```
+----
 
-## Attribute Pool
+=== Attribute Pool
 
-```javascript
+[source,javascript]
+----
 const AttributePool = require('ep_etherpad-lite/static/js/AttributePool');
-```
+----
 
 Changesets do not include any attribute key–value pairs. Instead, they use
-numeric identifiers that reference attributes kept in an [attribute
-pool](https://github.com/ether/etherpad-lite/blob/develop/src/static/js/AttributePool.js).
+numeric identifiers that reference attributes kept in an https://github.com/ether/etherpad-lite/blob/develop/src/static/js/AttributePool.js[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.
 
-## Further Reading
+=== Further Reading
 
 Detailed information about the changesets & Easysync protocol:
 
-* [Easysync Protocol](https://github.com/ether/etherpad-lite/blob/develop/doc/easysync/easysync-notes.pdf)
-* [Etherpad and EasySync Technical Manual](https://github.com/ether/etherpad-lite/blob/develop/doc/easysync/easysync-full-description.pdf)
+* https://github.com/ether/etherpad-lite/blob/develop/doc/easysync/easysync-notes.pdf[Easysync Protocol]
+* https://github.com/ether/etherpad-lite/blob/develop/doc/easysync/easysync-full-description.pdf[Etherpad and EasySync Technical Manual]

doc/api/editbar.adoc

@@ -1,28 +1,30 @@
-# Editbar
+== Editbar
 src/static/js/pad_editbar.js
 
-## isEnabled()
+=== isEnabled()
 
-## disable()
+=== disable()
 
-## toggleDropDown(dropdown)
+=== toggleDropDown(dropdown)
 Shows the dropdown `div.popup` whose `id` equals `dropdown`.
 
-## registerCommand(cmd, callback)
+=== registerCommand(cmd, callback)
 Register a handler for a specific command. Commands are fired if the corresponding button is clicked or the corresponding select is changed.
 
-## registerAceCommand(cmd, callback)
+=== registerAceCommand(cmd, callback)
 Creates an ace callstack and calls the callback with an ace instance (and a toolbar item, if applicable): `callback(cmd, ace, item)`.
 
 Example:
-```
+
+[source, javascript]
+----
 toolbar.registerAceCommand("insertorderedlist", function (cmd, ace) {
   ace.ace_doInsertOrderedList();
 });
-```
+----
 
-## registerDropdownCommand(cmd, dropdown)
+=== registerDropdownCommand(cmd, dropdown)
 Ties a `div.popup` where `id` equals `dropdown` to a `command` fired by clicking a button.
 
-## triggerCommand(cmd[, item])
+=== triggerCommand(cmd[, item])
 Triggers a command (optionally with some internal representation of the toolbar item that triggered it).

doc/api/editorInfo.adoc

@@ -0,0 +1,125 @@
+== editorInfo
+
+=== editorInfo.ace_replaceRange(start, end, text)
+This function replaces a range (from `start` to `end`) with `text`.
+
+=== editorInfo.ace_getRep()
+Returns the `rep` object.
+
+=== editorInfo.ace_getAuthor()
+
+=== editorInfo.ace_inCallStack()
+
+=== editorInfo.ace_inCallStackIfNecessary(?)
+
+=== editorInfo.ace_focus(?)
+
+=== editorInfo.ace_importText(?)
+
+=== editorInfo.ace_importAText(?)
+
+=== editorInfo.ace_exportText(?)
+
+=== editorInfo.ace_editorChangedSize(?)
+
+=== editorInfo.ace_setOnKeyPress(?)
+
+=== editorInfo.ace_setOnKeyDown(?)
+
+=== editorInfo.ace_setNotifyDirty(?)
+
+=== editorInfo.ace_dispose(?)
+
+=== editorInfo.ace_setEditable(bool)
+
+=== editorInfo.ace_execCommand(?)
+
+=== editorInfo.ace_callWithAce(fn, callStack, normalize)
+
+=== editorInfo.ace_setProperty(key, value)
+
+=== editorInfo.ace_setBaseText(txt)
+
+=== editorInfo.ace_setBaseAttributedText(atxt, apoolJsonObj)
+
+=== editorInfo.ace_applyChangesToBase(c, optAuthor, apoolJsonObj)
+
+=== editorInfo.ace_prepareUserChangeset()
+
+=== editorInfo.ace_applyPreparedChangesetToBase()
+
+=== editorInfo.ace_setUserChangeNotificationCallback(f)
+
+=== editorInfo.ace_setAuthorInfo(author, info)
+
+=== editorInfo.ace_fastIncorp(?)
+
+=== editorInfo.ace_isCaret(?)
+
+=== editorInfo.ace_getLineAndCharForPoint(?)
+
+=== editorInfo.ace_performDocumentApplyAttributesToCharRange(?)
+
+=== editorInfo.ace_setAttributeOnSelection(attribute, enabled)
+
+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
+
+=== editorInfo.ace_toggleAttributeOnSelection(?)
+
+=== editorInfo.ace_getAttributeOnSelection(attribute, prevChar)
+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.
+
+=== editorInfo.ace_performSelectionChange(?)
+
+=== editorInfo.ace_doIndentOutdent(?)
+
+=== editorInfo.ace_doUndoRedo(?)
+
+=== editorInfo.ace_doInsertUnorderedList(?)
+
+=== editorInfo.ace_doInsertOrderedList(?)
+
+=== editorInfo.ace_performDocumentApplyAttributesToRange()
+
+=== editorInfo.ace_getAuthorInfos()
+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.
+
+=== editorInfo.ace_performDocumentReplaceRange(start, end, newText)
+This function replaces a range (from [x1,y1] to [x2,y2]) with `newText`.
+
+=== editorInfo.ace_performDocumentReplaceCharRange(startChar, endChar, newText)
+This function replaces a range (from y1 to y2) with `newText`.
+
+=== editorInfo.ace_renumberList(lineNum)
+If you delete a line, calling this method will fix the line numbering.
+
+=== editorInfo.ace_doReturnKey()
+Forces a return key at the current caret position.
+
+=== editorInfo.ace_isBlockElement(element)
+Returns true if your passed element is registered as a block element
+
+=== editorInfo.ace_getLineListType(lineNum)
+Returns the line's html list type.
+
+=== editorInfo.ace_caretLine()
+Returns X position of the caret.
+
+=== editorInfo.ace_caretColumn()
+Returns Y position of the caret.
+
+=== editorInfo.ace_caretDocChar()
+Returns the Y offset starting from [x=0,y=0]
+
+=== editorInfo.ace_isWordChar(?)

doc/api/editorInfo.md

@@ -1,79 +0,0 @@
-# editorInfo
-
-## editorInfo.ace_replaceRange(start, end, text)
-This function replaces a range (from `start` to `end`) with `text`.
-
-## editorInfo.ace_getRep()
-Returns the `rep` object.
-
-## editorInfo.ace_getAuthor()
-## editorInfo.ace_inCallStack()
-## editorInfo.ace_inCallStackIfNecessary(?)
-## editorInfo.ace_focus(?)
-## editorInfo.ace_importText(?)
-## editorInfo.ace_importAText(?)
-## editorInfo.ace_exportText(?)
-## editorInfo.ace_editorChangedSize(?)
-## editorInfo.ace_setOnKeyPress(?)
-## editorInfo.ace_setOnKeyDown(?)
-## editorInfo.ace_setNotifyDirty(?)
-## editorInfo.ace_dispose(?)
-## editorInfo.ace_setEditable(bool)
-## editorInfo.ace_execCommand(?)
-## editorInfo.ace_callWithAce(fn, callStack, normalize)
-## editorInfo.ace_setProperty(key, value)
-## editorInfo.ace_setBaseText(txt)
-## editorInfo.ace_setBaseAttributedText(atxt, apoolJsonObj)
-## editorInfo.ace_applyChangesToBase(c, optAuthor, apoolJsonObj)
-## editorInfo.ace_prepareUserChangeset()
-## editorInfo.ace_applyPreparedChangesetToBase()
-## editorInfo.ace_setUserChangeNotificationCallback(f)
-## editorInfo.ace_setAuthorInfo(author, info)
-## editorInfo.ace_fastIncorp(?)
-## editorInfo.ace_isCaret(?)
-## editorInfo.ace_getLineAndCharForPoint(?)
-## editorInfo.ace_performDocumentApplyAttributesToCharRange(?)
-## editorInfo.ace_setAttributeOnSelection(attribute, enabled)
-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
-## editorInfo.ace_toggleAttributeOnSelection(?)
-## editorInfo.ace_getAttributeOnSelection(attribute, prevChar)
-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.
-## editorInfo.ace_performSelectionChange(?)
-## editorInfo.ace_doIndentOutdent(?)
-## editorInfo.ace_doUndoRedo(?)
-## editorInfo.ace_doInsertUnorderedList(?)
-## editorInfo.ace_doInsertOrderedList(?)
-## editorInfo.ace_performDocumentApplyAttributesToRange()
-
-## editorInfo.ace_getAuthorInfos()
-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.
-## editorInfo.ace_performDocumentReplaceRange(start, end, newText)
-This function replaces a range (from [x1,y1] to [x2,y2]) with `newText`.
-## editorInfo.ace_performDocumentReplaceCharRange(startChar, endChar, newText)
-This function replaces a range (from y1 to y2) with `newText`.
-## editorInfo.ace_renumberList(lineNum)
-If you delete a line, calling this method will fix the line numbering.
-## editorInfo.ace_doReturnKey()
-Forces a return key at the current caret position.
-## editorInfo.ace_isBlockElement(element)
-Returns true if your passed element is registered as a block element
-## editorInfo.ace_getLineListType(lineNum)
-Returns the line's html list type.
-## editorInfo.ace_caretLine()
-Returns X position of the caret.
-## editorInfo.ace_caretColumn()
-Returns Y position of the caret.
-## editorInfo.ace_caretDocChar()
-Returns the Y offset starting from [x=0,y=0]
-## editorInfo.ace_isWordChar(?)

doc/api/embed_parameters.adoc

@@ -1,72 +1,73 @@
-# Embed parameters
+== Embed parameters
 You can easily embed your etherpad-lite into any webpage by using iframes. You can configure the embedded pad using embed parameters.
 
 Example:
 
 Cut and paste the following code into any webpage to embed a pad. The parameters below will hide the chat and the line numbers and will auto-focus on Line 4.
 
-```
+[source, html]
+----
 <iframe src='http://pad.test.de/p/PAD_NAME#L4?showChat=false&showLineNumbers=false' width=600 height=400></iframe>
-```
+----
 
-## showLineNumbers
+=== showLineNumbers
  * Boolean
 
 Default: true
 
-## showControls
+=== showControls
  * Boolean
 
 Default: true
 
-## showChat
+=== showChat
  * Boolean
 
 Default: true
 
-## useMonospaceFont
+=== useMonospaceFont
  * Boolean
 
 Default: false
 
-## userName
+=== userName
  * String
 
 Default: "unnamed"
 
 Example: `userName=Etherpad%20User`
 
-## userColor
+=== userColor
  * String (css hex color value)
 
 Default: randomly chosen by pad server
 
 Example: `userColor=%23ff9900`
 
-## noColors
+=== noColors
  * Boolean
 
 Default: false
 
-## alwaysShowChat
+=== alwaysShowChat
  * Boolean
 
 Default: false
 
-## lang
+=== lang
  * String
 
 Default: en
 
 Example: `lang=ar` (translates the interface into Arabic)
 
-## rtl
+=== rtl
  * Boolean
 
 Default: true
 Displays pad text from right to left.
 
-## #L
+=== #L
  * Int
 
 Default: 0

doc/api/hooks_client-side.adoc

@@ -1,9 +1,9 @@
-# Client-side hooks
+== Client-side hooks
 
 Most of these hooks are called during or in order to set up the formatting
 process.
 
-## documentReady
+=== documentReady
 Called from: src/templates/pad.html
 
 Things in context:
@@ -12,7 +12,7 @@ nothing
 
 This hook proxies the functionality of jQuery's `$(document).ready` event.
 
-## aceDomLinePreProcessLineAttributes
+=== aceDomLinePreProcessLineAttributes
 
 Called from: src/static/js/domline.js
 
@@ -34,7 +34,7 @@ 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.
 
-## aceDomLineProcessLineAttributes
+=== aceDomLineProcessLineAttributes
 
 Called from: src/static/js/domline.js
 
@@ -56,7 +56,7 @@ 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.
 
-## aceCreateDomLine
+=== aceCreateDomLine
 
 Called from: src/static/js/domline.js
 
@@ -76,7 +76,7 @@ The return value of this hook should have the following structure:
 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.
 
-## acePostWriteDomLineHTML
+=== acePostWriteDomLineHTML
 
 Called from: src/static/js/domline.js
 
@@ -87,7 +87,7 @@ Things in context:
 This hook is for right after a node has been fully formatted and written to the
 page.
 
-## aceAttribsToClasses
+=== aceAttribsToClasses
 
 Called from: src/static/js/linestylefilter.js
 
@@ -105,7 +105,7 @@ 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.
 
-## aceAttribClasses
+=== aceAttribClasses
 
 Called from: src/static/js/linestylefilter.js
 
@@ -116,14 +116,16 @@ 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:
-```
+
+[source,javascript]
+----
 exports.aceAttribClasses = function(hook_name, attr, cb){
   attr.sub = 'tag:sub';
   cb(attr);
 }
-```
+----
 
-## aceGetFilterStack
+=== aceGetFilterStack
 
 Called from: src/static/js/linestylefilter.js
 
@@ -139,7 +141,7 @@ 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).
 
-## aceEditorCSS
+=== aceEditorCSS
 
 Called from: src/static/js/ace.js
 
@@ -148,7 +150,7 @@ 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.
 
-## aceInitInnerdocbodyHead
+=== aceInitInnerdocbodyHead
 
 Called from: src/static/js/ace.js
 
@@ -161,7 +163,7 @@ 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.
 
-## aceEditEvent
+=== aceEditEvent
 
 Called from: src/static/js/ace2_inner.js
 
@@ -178,7 +180,7 @@ 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.
 
-## aceRegisterNonScrollableEditEvents
+=== aceRegisterNonScrollableEditEvents
 
 Called from: src/static/js/ace2_inner.js
 
@@ -191,13 +193,15 @@ not scroll viewport. The return value of this hook should be a list of event
 names.
 
 Example:
-```
+
+[source, javascript]
+----
 exports.aceRegisterNonScrollableEditEvents = function(){
   return [ 'repaginate', 'updatePageCount' ];
 }
-```
+----
 
-## aceRegisterBlockElements
+=== aceRegisterBlockElements
 
 Called from: src/static/js/ace2_inner.js
 
@@ -207,7 +211,7 @@ The return value of this hook will add elements into the "lineMarkerAttribute"
 category, making the aceDomLineProcessLineAttributes hook (documented below)
 call for those elements.
 
-## aceInitialized
+=== aceInitialized
 
 Called from: src/static/js/ace2_inner.js
 
@@ -222,7 +226,7 @@ Things in context:
 This hook is for inserting further information into the ace engine, for later
 use in formatting hooks.
 
-## postAceInit
+=== postAceInit
 
 Called from: src/static/js/pad.js
 
@@ -234,7 +238,7 @@ Things in context:
    `clientVars` server-side hook.
 3. pad - the pad object of the current pad.
 
-## postToolbarInit
+=== postToolbarInit
 
 Called from: src/static/js/pad_editbar.js
 
@@ -247,16 +251,16 @@ Can be used to register custom actions to the toolbar.
 
 Usage examples:
 
-* [https://github.com/tiblu/ep_authorship_toggle]()
+* https://github.com/tiblu/ep_authorship_toggle
 
-## postTimesliderInit
+=== postTimesliderInit
 
 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.
 
-## goToRevisionEvent
+=== goToRevisionEvent
 
 Called from: src/static/js/broadcast.js
 
@@ -268,7 +272,7 @@ 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.
 
-## userJoinOrUpdate
+=== userJoinOrUpdate
 
 Called from: src/static/js/pad_userlist.js
 
@@ -279,7 +283,7 @@ 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.
 
-## `chatNewMessage`
+=== `chatNewMessage`
 
 Called from: `src/static/js/chat.js`
 
@@ -315,7 +319,7 @@ Context properties:
 * `duration`: How long (in milliseconds) to display the gritter notification (0
   to disable).
 
-## `chatSendMessage`
+=== `chatSendMessage`
 
 Called from: `src/static/js/chat.js`
 
@@ -327,7 +331,7 @@ Context properties:
 
 * `message`: The message object that will be sent to the Etherpad server.
 
-## collectContentPre
+=== collectContentPre
 
 Called from: src/static/js/contentcollector.js
 
@@ -351,7 +355,7 @@ If you want to specify also a value, call cc.doAttrib(state,
 "attributeName::value") which results in an attribute attributeName=value.
 
 
-## collectContentImage
+=== collectContentImage
 
 Called from: src/static/js/contentcollector.js
 
@@ -370,14 +374,15 @@ content of the pad.
 
 Example:
 
-```
+[source, javascript]
+----
 exports.collectContentImage = function(name, context){
   context.state.lineAttributes.img = context.node.outerHTML;
 }
 
-```
+----
 
-## collectContentPost
+=== collectContentPost
 
 Called from: src/static/js/contentcollector.js
 
@@ -393,7 +398,7 @@ 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.
 
-## handleClientMessage_`name`
+=== handleClientMessage_`name`
 
 Called from: `src/static/js/collab_client.js`
 
@@ -410,7 +415,7 @@ 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.
 
-## aceStartLineAndCharForPoint-aceEndLineAndCharForPoint
+=== aceStartLineAndCharForPoint-aceEndLineAndCharForPoint
 
 Called from: src/static/js/ace2_inner.js
 
@@ -426,7 +431,7 @@ Things in context:
 This hook is provided to allow a plugin to turn DOM node selection into
 [line,char] selection. The return value should be an array of [line,char]
 
-## aceKeyEvent
+=== aceKeyEvent
 
 Called from: src/static/js/ace2_inner.js
 
@@ -441,7 +446,7 @@ 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.
 
-## collectContentLineText
+=== collectContentLineText
 
 Called from: src/static/js/contentcollector.js
 
@@ -462,13 +467,14 @@ server side. To change the text, either:
 
 Example:
 
-```
+[source,javascript]
+----
 exports.collectContentLineText = (hookName, context) => {
   context.text = tweakText(context.text);
 };
-```
+----
 
-## collectContentLineBreak
+=== collectContentLineBreak
 
 Called from: src/static/js/contentcollector.js
 
@@ -481,7 +487,7 @@ 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.
 
-## disableAuthorColorsForThisLine
+=== disableAuthorColorsForThisLine
 
 Called from: src/static/js/linestylefilter.js
 
@@ -497,7 +503,7 @@ 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.
 
-## aceSetAuthorStyle
+=== aceSetAuthorStyle
 
 Called from: src/static/js/ace2_inner.js
 
@@ -514,7 +520,7 @@ 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.
 
-## aceSelectionChanged
+=== aceSelectionChanged
 
 Called from: src/static/js/ace2_inner.js
 

doc/api/hooks_overview.adoc

@@ -1,4 +1,4 @@
-# Hooks
+== Hooks
 
 A hook function is registered with a hook via the plugin's `ep.json` file. See
 the Plugins section for details. A hook may have many registered functions from
@@ -8,12 +8,12 @@ Some hooks call their registered functions one at a time until one of them
 returns a value. Others always call all of their registered functions and
 combine the results (if applicable).
 
-## Registered hook functions
+=== Registered hook functions
 
 Note: The documentation in this section applies to every hook unless the
 hook-specific documentation says otherwise.
 
-### Arguments
+==== Arguments
 
 Hook functions are called with three arguments:
 
@@ -26,7 +26,7 @@ Hook functions are called with three arguments:
    section for general information that applies to most hooks). This callback
    always returns `undefined`.
 
-### Expected behavior
+==== Expected behavior
 
 The presence of a callback parameter suggests that every hook function can run
 asynchronously. While that is the eventual goal, there are some legacy hooks
@@ -54,15 +54,13 @@ Note that the acceptable behaviors for asynchronous hook functions is a superset
 of the acceptable behaviors for synchronous hook functions.
 
 WARNING: The number of parameters is determined by examining
-[Function.length](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/length),
-which does not count [default
-parameters](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Default_parameters)
-or ["rest"
-parameters](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/rest_parameters).
+https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/length[Function.length],
+which does not count https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Default_parameters[default parameters]
+or https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/rest_parameters["rest" parameters].
 To avoid problems, do not use default or rest parameters when defining hook
 functions.
 
-### Return values
+==== Return values
 
 A hook function can provide a value to Etherpad in one of the following ways:
 
@@ -77,7 +75,8 @@ A hook function can provide a value to Etherpad in one of the following ways:
 
 Examples:
 
-```javascript
+[source,javascript]
+----
 exports.exampleOne = (hookName, context, callback) => {
   return 'valueOne';
 };
@@ -104,7 +103,7 @@ exports.exampleFive = async (hookName, context) => {
   // is resolved to 'valueFive'.
   return 'valueFive';
 };
-```
+----
 
 Etherpad collects the values provided by the hook functions into an array,
 filters out all `undefined` values, then flattens the array one level.

doc/api/hooks_server-side.adoc

@@ -1,7 +1,7 @@
-# Server-side hooks
+== Server-side hooks
 These hooks are called on server-side.
 
-## loadSettings
+=== loadSettings
 Called from: src/node/server.js
 
 Things in context:
@@ -10,7 +10,7 @@ Things in context:
 
 Use this hook to receive the global settings in your plugin.
 
-## shutdown
+=== shutdown
 Called from: src/node/server.js
 
 Things in context: None
@@ -25,14 +25,15 @@ Returning `callback(value)` will return a Promise that is resolved to `value`.
 
 Example:
 
-```
+[source, javascript]
+----
 // using an async function
 exports.shutdown = async (hookName, context) => {
   await flushBuffers();
 };
-```
+----
 
-## pluginUninstall
+=== pluginUninstall
 Called from: src/static/js/pluginfw/installer.js
 
 Things in context:
@@ -41,7 +42,7 @@ 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!
 
-## pluginInstall
+=== pluginInstall
 Called from: src/static/js/pluginfw/installer.js
 
 Things in context:
@@ -50,7 +51,7 @@ 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.
 
-## `init_<plugin name>`
+=== `init_<plugin name>`
 
 Called from: `src/static/js/pluginfw/plugins.js`
 
@@ -61,12 +62,12 @@ Context properties:
   * `logger`: An object with the following `console`-like methods: `debug`,
     `info`, `log`, `warn`, `error`.
 
-## `expressPreSession`
+=== `expressPreSession`
 
 Called from: `src/node/hooks/express.js`
 
 Called during server startup just before the
-[`express-session`](https://www.npmjs.com/package/express-session) middleware is
+https://www.npmjs.com/package/express-session[`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
@@ -79,33 +80,34 @@ handler itself authenticates the user.
 
 Context properties:
 
-* `app`: The Express [Application](https://expressjs.com/en/4x/api.html#app)
+* `app`: The Express https://expressjs.com/en/4x/api.html==app[Application]
   object.
 
 Example:
 
-```javascript
+[source,javascript]
+----
 exports.expressPreSession = async (hookName, {app}) => {
   app.get('/hello-world', (req, res) => res.send('hello world'));
 };
-```
+----
 
-## `expressConfigure`
+=== `expressConfigure`
 
 Called from: `src/node/hooks/express.js`
 
 Called during server startup just after the
-[`express-session`](https://www.npmjs.com/package/express-session) middleware is
+https://www.npmjs.com/package/express-session[`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:
 
-* `app`: The Express [Application](https://expressjs.com/en/4x/api.html#app)
+* `app`: The Express https://expressjs.com/en/4x/api.html==app[Application]
   object.
 
-## `expressCreateServer`
+=== `expressCreateServer`
 
 Called from: `src/node/hooks/express.js`
 
@@ -114,12 +116,12 @@ other) except this hook's context includes the HTTP Server object.
 
 Context properties:
 
-* `app`: The Express [Application](https://expressjs.com/en/4x/api.html#app)
+* `app`: The Express https://expressjs.com/en/4x/api.html==app[Application]
   object.
-* `server`: The [http.Server](https://nodejs.org/api/http.html#class-httpserver)
-  or [https.Server](https://nodejs.org/api/https.html#class-httpsserver) object.
+* `server`: The https://nodejs.org/api/http.html==class-httpserver[http.Server]
+  or https://nodejs.org/api/https.html==class-httpsserver[https.Server] object.
 
-## expressCloseServer
+=== expressCloseServer
 
 Called from: src/node/hooks/express.js
 
@@ -132,13 +134,14 @@ not already be closed when this hook executes.
 
 Example:
 
-```
+[source, javascript]
+----
 exports.expressCloseServer = async () => {
   await doSomeCleanup();
 };
-```
+----
 
-## eejsBlock_`<name>`
+=== eejsBlock_`<name>`
 Called from: src/node/eejs/index.js
 
 Things in context:
@@ -181,7 +184,7 @@ Available blocks in `pad.html` are:
  * `indexWrapper` - contains the form for creating new pads
  * `indexCustomScripts` - contains the `index.js` `<script>` tag, allows you to add your own or to customize the one provided by the active skin
 
-## padInitToolbar
+=== padInitToolbar
 Called from: src/node/hooks/express/specialpages.js
 
 Things in context:
@@ -194,7 +197,7 @@ Usage examples:
 
 * https://github.com/tiblu/ep_authorship_toggle
 
-## onAccessCheck
+=== onAccessCheck
 Called from: src/node/db/SecurityManager.js
 
 Things in context:
@@ -207,7 +210,7 @@ Things in context:
 This hook gets called when the access to the concrete pad is being checked.
 Return `false` to deny access.
 
-## `getAuthorId`
+=== `getAuthorId`
 
 Called from `src/node/db/AuthorManager.js`
 
@@ -243,7 +246,8 @@ Context properties:
 
 Example:
 
-```javascript
+[source,javascript]
+----
 exports.getAuthorId = async (hookName, context) => {
   const {username} = context.user || {};
   // If the user has not authenticated, or has "authenticated" as the guest
@@ -261,9 +265,9 @@ exports.getAuthorId = async (hookName, context) => {
   // username-derived database key.
   return '';
 };
-```
+----
 
-## `padCreate`
+=== `padCreate`
 
 Called from: `src/node/db/Pad.js`
 
@@ -275,7 +279,7 @@ Context properties:
 * `authorId`: The ID of the author who created the pad.
 * `author` (**deprecated**): Synonym of `authorId`.
 
-## `padDefaultContent`
+=== `padDefaultContent`
 
 Called from `src/node/db/Pad.js`
 
@@ -300,7 +304,7 @@ Context properties:
   be updated to match. Plugins must check the value of the `type` property
   before reading this value.
 
-## `padLoad`
+=== `padLoad`
 
 Called from: `src/node/db/PadManager.js`
 
@@ -310,7 +314,8 @@ Context properties:
 
 * `pad`: The Pad object.
 
-## `padUpdate`
+[#_padupdate]
+=== `padUpdate`
 
 Called from: `src/node/db/Pad.js`
 
@@ -322,10 +327,9 @@ Context properties:
 * `authorId`: The ID of the author who updated the pad.
 * `author` (**deprecated**): Synonym of `authorId`.
 * `revs`: The index of the new revision.
-* `changeset`: The changeset of this revision (see [Changeset
-  Library](#index_changeset_library)).
+* `changeset`: The changeset of this revision (see <<_padupdate>>).
 
-## `padCopy`
+=== `padCopy`
 
 Called from: `src/node/db/Pad.js`
 
@@ -351,7 +355,7 @@ Usage examples:
 
   * https://github.com/ether/ep_comments_page
 
-## `padRemove`
+=== `padRemove`
 
 Called from: `src/node/db/Pad.js`
 
@@ -366,7 +370,7 @@ Usage examples:
 
   * https://github.com/ether/ep_comments_page
 
-## `padCheck`
+=== `padCheck`
 
 Called from: `src/node/db/Pad.js`
 
@@ -378,7 +382,7 @@ Context properties:
 
   * `pad`: The Pad object that is being checked.
 
-## socketio
+=== socketio
 Called from: src/node/hooks/express/socketio.js
 
 Things in context:
@@ -389,7 +393,7 @@ Things in context:
 
 I have no idea what this is useful for, someone else will have to add this description.
 
-## `preAuthorize`
+=== `preAuthorize`
 
 Called from: `src/node/hooks/express/webaccess.js`
 
@@ -420,8 +424,8 @@ Return values:
 
 Context properties:
 
-* `req`: The Express [Request](https://expressjs.com/en/4x/api.html#req) object.
-* `res`: The Express [Response](https://expressjs.com/en/4x/api.html#res)
+* `req`: The Express https://expressjs.com/en/4x/api.html==req[Request] object.
+* `res`: The Express https://expressjs.com/en/4x/api.html==res[Response]
   object.
 * `next`: Callback to immediately hand off handling to the next Express
   middleware/handler, or to the next matching route if `'route'` is passed as
@@ -429,16 +433,17 @@ Context properties:
 
 Example:
 
-```javascript
+[source,javascript]
+----
 exports.preAuthorize = async (hookName, {req}) => {
   if (await ipAddressIsFirewalled(req)) return false;
   if (requestIsForStaticContent(req)) return true;
   if (requestIsForOAuthCallback(req)) return true;
   // Defer the decision to the next step by returning undefined.
 };
-```
+----
 
-## authorize
+=== authorize
 Called from: src/node/hooks/express/webaccess.js
 
 Things in context:
@@ -484,7 +489,8 @@ You can pass the following values to the provided callback:
 
 Example:
 
-```
+[source, javascript]
+----
 exports.authorize = (hookName, context, cb) => {
   const user = context.req.session.user;
   const path = context.req.path;  // or context.resource
@@ -492,9 +498,9 @@ exports.authorize = (hookName, context, cb) => {
   if (isExplicitlyAllowed(user, path)) return cb([true]);
   return cb([]);  // Let the next authorization plugin decide
 };
-```
+----
 
-## authenticate
+=== authenticate
 Called from: src/node/hooks/express/webaccess.js
 
 Things in context:
@@ -532,7 +538,8 @@ object should come from global settings (`context.users[username]`).
 
 Example:
 
-```
+[source, javascript]
+----
 exports.authenticate = (hook_name, context, cb) => {
   if (notApplicableToThisPlugin(context)) {
     return cb([]);  // Let the next authentication plugin decide
@@ -549,9 +556,9 @@ exports.authenticate = (hook_name, context, cb) => {
   context.req.session.user = users[username];
   return cb([true]);
 };
-```
+----
 
-## authFailure
+=== authFailure
 Called from: src/node/hooks/express/webaccess.js
 
 Things in context:
@@ -586,7 +593,8 @@ failure or a generic 403 page for an authorization failure).
 
 Example:
 
-```
+[source, javascript]
+----
 exports.authFailure = (hookName, context, cb) => {
   if (notApplicableToThisPlugin(context)) {
     return cb([]);  // Let the next plugin handle the error
@@ -594,9 +602,9 @@ exports.authFailure = (hookName, context, cb) => {
   context.res.redirect(makeLoginURL(context.req));
   return cb([true]);
 };
-```
+----
 
-## preAuthzFailure
+=== preAuthzFailure
 Called from: src/node/hooks/express/webaccess.js
 
 Things in context:
@@ -617,15 +625,16 @@ another plugin (if any, otherwise fall back to a generic 403 error page).
 
 Example:
 
-```
+[source, javascript]
+----
 exports.preAuthzFailure = (hookName, context, cb) => {
   if (notApplicableToThisPlugin(context)) return cb([]);
   context.res.status(403).send(renderFancy403Page(context.req));
   return cb([true]);
 };
-```
+----
 
-## authnFailure
+=== authnFailure
 Called from: src/node/hooks/express/webaccess.js
 
 Things in context:
@@ -649,15 +658,16 @@ another plugin (if any, otherwise fall back to the deprecated authFailure hook).
 
 Example:
 
-```
+[source, javascript]
+----
 exports.authnFailure = (hookName, context, cb) => {
   if (notApplicableToThisPlugin(context)) return cb([]);
   context.res.redirect(makeLoginURL(context.req));
   return cb([true]);
 };
-```
+----
 
-## authzFailure
+=== authzFailure
 Called from: src/node/hooks/express/webaccess.js
 
 Things in context:
@@ -677,7 +687,8 @@ another plugin (if any, otherwise fall back to the deprecated authFailure hook).
 
 Example:
 
-```
+[source, javascript]
+----
 exports.authzFailure = (hookName, context, cb) => {
   if (notApplicableToThisPlugin(context)) return cb([]);
   if (needsPremiumAccount(context.req) && !context.req.session.user.premium) {
@@ -687,9 +698,9 @@ exports.authzFailure = (hookName, context, cb) => {
   // Use the generic 403 forbidden response.
   return cb([]);
 };
-```
+----
 
-## `handleMessage`
+=== `handleMessage`
 
 Called from: `src/node/handler/PadMessageHandler.js`
 
@@ -711,7 +722,8 @@ Context properties:
 
 Example:
 
-```javascript
+[source,javascript]
+----
 exports.handleMessage = async (hookName, {message, socket}) => {
   if (message.type === 'USERINFO_UPDATE') {
     // Force the display name to the name associated with the account.
@@ -719,9 +731,9 @@ exports.handleMessage = async (hookName, {message, socket}) => {
     if (user.name) message.data.userInfo.name = user.name;
   }
 };
-```
+----
 
-## `handleMessageSecurity`
+=== `handleMessageSecurity`
 
 Called from: `src/node/handler/PadMessageHandler.js`
 
@@ -755,15 +767,16 @@ Context properties:
 
 Example:
 
-```javascript
+[source,javascript]
+----
 exports.handleMessageSecurity = async (hookName, context) => {
   const {message, sessionInfo: {readOnly}} = context;
   if (!readOnly || message.type !== 'COLLABROOM') return;
   if (await messageIsBenign(message)) return 'permitOnce';
 };
-```
+----
 
-## clientVars
+=== clientVars
 Called from: src/node/handler/PadMessageHandler.js
 
 Things in context:
@@ -791,7 +804,8 @@ If needed, you can access the user's account information (if authenticated) via
 
 Examples:
 
-```
+[source, javascript]
+----
 // Using an async function
 exports.clientVars = async (hookName, context) => {
   const user = context.socket.client.request.session.user || {};
@@ -803,9 +817,9 @@ exports.clientVars = (hookName, context, callback) => {
   const user = context.socket.client.request.session.user || {};
   return callback({'accountUsername': user.username || '<unknown>'});
 };
-```
+----
 
-## `getLineHTMLForExport`
+=== `getLineHTMLForExport`
 
 Called from: `src/node/utils/ExportHtml.js`
 
@@ -823,7 +837,8 @@ Context properties:
 
 Example:
 
-```javascript
+[source,javascript]
+----
 const AttributeMap = require('ep_etherpad-lite/static/js/AttributeMap');
 const Changeset = require('ep_etherpad-lite/static/js/Changeset');
 
@@ -835,9 +850,9 @@ exports.getLineHTMLForExport = async (hookName, context) => {
   if (!heading) return;
   context.lineContent = `<${heading}>${context.lineContent}</${heading}>`;
 };
-```
+----
 
-## exportHTMLAdditionalContent
+=== exportHTMLAdditionalContent
 Called from: src/node/utils/ExportHtml.js
 
 Things in context:
@@ -849,13 +864,14 @@ the body of the exported HTML.
 
 Example:
 
-```
+[source, javascript]
+----
 exports.exportHTMLAdditionalContent = async (hookName, {padId}) => {
   return 'I am groot in ' + padId;
 };
-```
+----
 
-## stylesForExport
+=== stylesForExport
 Called from: src/node/utils/ExportHtml.js
 
 Things in context:
@@ -866,13 +882,14 @@ This hook will allow a plug-in developer to append Styles to the Exported HTML.
 
 Example:
 
-```
+[source, javascript]
+----
 exports.stylesForExport = function(hook, padId, cb){
   cb("body{font-size:13.37em !important}");
 }
-```
+----
 
-## aceAttribClasses
+=== aceAttribClasses
 Called from: src/static/js/linestylefilter.js
 
 This hook is called when attributes are investigated on a line. It is useful if
@@ -884,15 +901,16 @@ or provide an object whose properties will be assigned to the attributes object.
 
 Example:
 
-```
+[source, javascript]
+----
 exports.aceAttribClasses = (hookName, attrs, cb) => {
   return cb([{
     sub: 'tag:sub',
   }]);
 };
-```
+----
 
-## exportFileName
+=== exportFileName
 Called from src/node/handler/ExportHandler.js
 
 Things in context:
@@ -903,13 +921,14 @@ This hook will allow a plug-in developer to modify the file name of an exported
 
 Example:
 
-```
+[source, javascript]
+----
 exports.exportFileName = function(hook, padId, callback){
   callback("newFileName"+padId);
 }
-```
+----
 
-## exportHtmlAdditionalTags
+=== exportHtmlAdditionalTags
 Called from src/node/utils/ExportHtml.js
 
 Things in context:
@@ -919,15 +938,17 @@ 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:
-```
+
+[source, javascript]
+----
 // Add the props to be supported in export
 exports.exportHtmlAdditionalTags = function(hook, pad, cb){
   var padId = pad.id;
   cb(["massive","jugs"]);
 };
-```
+----
 
-## exportHtmlAdditionalTagsWithData
+=== exportHtmlAdditionalTagsWithData
 Called from src/node/utils/ExportHtml.js
 
 Things in context:
@@ -937,15 +958,17 @@ 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:
-```
+
+[source, javascript]
+----
 // Add the props to be supported in export
 exports.exportHtmlAdditionalTagsWithData = function(hook, pad, cb){
   var padId = pad.id;
   cb([["color", "red"], ["color", "blue"]]);
 };
-```
+----
 
-## `exportEtherpadAdditionalContent`
+=== `exportEtherpadAdditionalContent`
 
 Called from `src/node/utils/ExportEtherpad.js` and
 `src/node/utils/ImportEtherpad.js`.
@@ -961,12 +984,13 @@ Context properties: None.
 
 Example:
 
-```
+[source, javascript]
+----
 // Add support for exporting comments metadata
 exports.exportEtherpadAdditionalContent = () => ['comments'];
-```
+----
 
-## `exportEtherpad`
+=== `exportEtherpad`
 
 Called from `src/node/utils/ExportEtherpad.js`.
 
@@ -989,7 +1013,7 @@ Context properties:
     should not assume that it is either the pad's real writable ID or its
     read-only ID.
 
-## `importEtherpad`
+=== `importEtherpad`
 
 Called from `src/node/utils/ImportEtherpad.js`.
 
@@ -1008,7 +1032,7 @@ Context properties:
     modified.
   * `srcPadId`: The pad ID used for the pad-specific information in `data`.
 
-## `import`
+=== `import`
 
 Called from: `src/node/handler/ImportHandler.js`
 
@@ -1026,18 +1050,19 @@ Context properties:
 * `ImportError`: Subclass of Error that can be thrown to provide a specific
   error message to the user. The constructor's first argument must be a string
   matching one of the [known error
-  identifiers](https://github.com/ether/etherpad-lite/blob/1.8.16/src/static/js/pad_impexp.js#L80-L86).
+  identifiers](https://github.com/ether/etherpad-lite/blob/1.8.16/src/static/js/pad_impexp.js==L80-L86).
 
 Example:
 
-```javascript
+[source,javascript]
+----
 exports.import = async (hookName, {fileEnding, ImportError}) => {
   // Reject all *.etherpad imports with a permission denied message.
   if (fileEnding === '.etherpad') throw new ImportError('permission');
 };
-```
+----
 
-## `userJoin`
+=== `userJoin`
 
 Called from: `src/node/handler/PadMessageHandler.js`
 
@@ -1061,7 +1086,7 @@ exports.userJoin = async (hookName, {authorId, displayName, padId}) => {
 };
 ```
 
-## `userLeave`
+=== `userLeave`
 
 Called from: `src/node/handler/PadMessageHandler.js`
 
@@ -1078,13 +1103,14 @@ Context properties:
 
 Example:
 
-```javascript
+[source,javascript]
+----
 exports.userLeave = async (hookName, {author, padId}) => {
   console.log(`${author} left pad ${padId}`);
 };
-```
+----
 
-## `chatNewMessage`
+=== `chatNewMessage`
 
 Called from: `src/node/handler/PadMessageHandler.js`
 

doc/api/http_api.adoc

@@ -1,6 +1,6 @@
-# HTTP API
+== HTTP API
 
-## What can I do with this API?
+=== What can I do with this API?
 The API gives another web application control of the pads. The basic functions are
 
 * create/delete pads
@@ -9,15 +9,15 @@ The API gives another web application control of the pads. The basic functions a
 
 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](https://github.com/ether/etherpad-lite/wiki/HTTP-API-client-libraries) to check if a library in your favorite programming language is available.
+Take a look at https://github.com/ether/etherpad-lite/wiki/HTTP-API-client-libraries[HTTP API client libraries] to check if a library in your favorite programming language is available.
 
-### OpenAPI
+==== OpenAPI
 
-OpenAPI (formerly swagger) definitions are exposed under `/api/openapi.json` (latest) and `/api/{version}/openapi.json`. You can use official tools like [Swagger Editor](https://editor.swagger.io/) to view and explore them.
+OpenAPI (formerly swagger) definitions are exposed under `/api/openapi.json` (latest) and `/api/{version}/openapi.json`. You can use official tools like https://editor.swagger.io/[Swagger Editor] to view and explore them.
 
-## Examples
+=== Examples
 
-### Example 1
+==== Example 1
 
 A portal (such as WordPress) wants to give a user access to a new pad. Let's assume the user have the internal id 7 and his name is michael.
 
@@ -47,7 +47,7 @@ Portal starts the session for the user on the group:
 
 Portal places the cookie "sessionID" with the given value on the client and creates an iframe including the pad.
 
-### Example 2
+==== Example 2
 
 A portal (such as WordPress) wants to transform the contents of a pad that multiple admins edited into a blog post.
 
@@ -62,14 +62,14 @@ Portal submits content into new blog post
 > Portal.AddNewBlog(content)
 >
 
-## Usage
+=== Usage
 
-### API version
+==== API version
 The latest version is `1.2.15`
 
 The current version can be queried via /api.
 
-### Request Format
+==== Request Format
 
 The API is accessible via HTTP. Starting from **1.8**, API endpoints can be invoked indifferently via GET or POST.
 
@@ -80,30 +80,37 @@ When invoking via GET (mandatory until **1.7.5** included), parameters must be i
 Starting from Etherpad **1.8** it is also possible to invoke the HTTP API via POST. In this case, querystring parameters will still be accepted, but **any parameter with the same name sent via POST will take precedence**. If you need to send large chunks of text (for example, for `setText()`) it is advisable to invoke via POST.
 
 Example with cURL using GET (toy example, no encoding):
-```
+
+[source,bash]
+----
 curl "http://pad.domain/api/1/setText?apikey=secret&padID=padname&text=this_text_will_NOT_be_encoded_by_curl_use_next_example"
-```
+----
 
 Example with cURL using GET (better example, encodes text):
-```
+
+[source,bash]
+----
 curl "http://pad.domain/api/1/setText?apikey=secret&padID=padname" --get --data-urlencode "text=Text sent via GET with proper encoding. For big documents, please use POST"
-```
+----
 
 Example with cURL using POST:
-```
-curl "http://pad.domain/api/1/setText?apikey=secret&padID=padname" --data-urlencode "text=Text sent via POST with proper encoding. For big texts (>8 KB), use this method"
-```
 
-### Response Format
+[source,bash]
+----
+curl "http://pad.domain/api/1/setText?apikey=secret&padID=padname" --data-urlencode "text=Text sent via POST with proper encoding. For big texts (>8 KB), use this method"
+----
+
+==== Response Format
 Responses are valid JSON in the following format:
 
-```json
+[source,jsonlines]
+----
 {
   "code": number,
   "message": string,
   "data": obj
 }
-```
+----
 
 * **code** a return code
   * **0** everything ok
@@ -114,11 +121,11 @@ Responses are valid JSON in the following format:
 * **message** a status message. It's ok if everything is fine, else it contains an error message
 * **data** the payload
 
-### Overview
+==== Overview
 
-![API Overview](https://i.imgur.com/d0nWp.png)
+image::https://i.imgur.com/d0nWp.png[API Overview]
 
-## Data Types
+=== Data Types
 
 * **groupID**  a string, the unique id of a group. Format is g.16RANDOMCHARS, for example g.s8oes9dhwrvt0zif
 * **sessionID** a string, the unique id of a session. Format is s.16RANDOMCHARS, for example s.s8oes9dhwrvt0zif
@@ -126,175 +133,191 @@ Responses are valid JSON in the following format:
 * **readOnlyID** a string, the unique id of a readonly relation to a pad. Format is r.16RANDOMCHARS, for example r.s8oes9dhwrvt0zif
 * **padID** a string, format is GROUPID$PADNAME, for example the pad test of group g.s8oes9dhwrvt0zif has padID g.s8oes9dhwrvt0zif$test
 
-### Authentication
+==== Authentication
 
 Authentication works via a token that is sent with each request as a post parameter.  There is a single token per Etherpad deployment.  This token will be random string, generated by Etherpad at the first start. It will be saved in APIKEY.txt in the root folder of Etherpad. Only Etherpad and the requesting application knows this key. Token management will not be exposed through this API.
 
-### Node Interoperability
+==== Node Interoperability
 
 All functions will also be available through a node module accessible from other node.js applications.
 
-## API Methods
+=== API Methods
 
-### Groups
+==== Groups
 Pads can belong to a group. The padID of grouppads is starting with a groupID like g.asdfasdfasdfasdf$test
 
-#### createGroup()
+===== createGroup()
  * API >= 1
 
 creates a new group
 
-*Example returns:*
+_Example returns:_
+
 * `{code: 0, message:"ok", data: {groupID: g.s8oes9dhwrvt0zif}}`
 
-#### createGroupIfNotExistsFor(groupMapper)
+===== createGroupIfNotExistsFor(groupMapper)
  * API >= 1
 
 this functions helps you to map your application group ids to Etherpad group ids
 
-*Example returns:*
+_Example returns:_
+
   * `{code: 0, message:"ok", data: {groupID: g.s8oes9dhwrvt0zif}}`
 
-#### deleteGroup(groupID)
+===== deleteGroup(groupID)
  * API >= 1
 
 deletes a group
 
-*Example returns:*
+_Example returns:_
+
   * `{code: 0, message:"ok", data: null}`
   * `{code: 1, message:"groupID does not exist", data: null}`
 
-#### listPads(groupID)
+===== listPads(groupID)
  * API >= 1
 
 returns all pads of this group
 
-*Example returns:*
+_Example returns:_
+
   * `{code: 0, message:"ok", data: {padIDs : ["g.s8oes9dhwrvt0zif$test", "g.s8oes9dhwrvt0zif$test2"]}`
   * `{code: 1, message:"groupID does not exist", data: null}`
 
-#### createGroupPad(groupID, padName, [text], [authorId])
+===== createGroupPad(groupID, padName, [text], [authorId])
  * API >= 1
  * `authorId` in API >= 1.3.0
 
 creates a new pad in this group
 
-*Example returns:*
+_Example returns:_
+
   * `{code: 0, message:"ok", data: {padID: "g.s8oes9dhwrvt0zif$test"}`
   * `{code: 1, message:"padName does already exist", data: null}`
   * `{code: 1, message:"groupID does not exist", data: null}`
 
-#### listAllGroups()
+===== listAllGroups()
  * API >= 1.1
 
 lists all existing groups
 
-*Example returns:*
+_Example returns:_
+
   * `{code: 0, message:"ok", data: {groupIDs: ["g.mKjkmnAbSMtCt8eL", "g.3ADWx6sbGuAiUmCy"]}}`
   * `{code: 0, message:"ok", data: {groupIDs: []}}`
 
-### Author
+==== Author
 These authors are bound to the attributes the users choose (color and name).
 
-#### createAuthor([name])
+===== createAuthor([name])
  * API >= 1
 
 creates a new author
 
-*Example returns:*
+_Example returns:_
+
   * `{code: 0, message:"ok", data: {authorID: "a.s8oes9dhwrvt0zif"}}`
 
-#### createAuthorIfNotExistsFor(authorMapper [, name])
+===== createAuthorIfNotExistsFor(authorMapper [, name])
  * API >= 1
 
 this functions helps you to map your application author ids to Etherpad author ids
 
-*Example returns:*
+_Example returns:_
+
   * `{code: 0, message:"ok", data: {authorID: "a.s8oes9dhwrvt0zif"}}`
 
-#### listPadsOfAuthor(authorID)
+===== listPadsOfAuthor(authorID)
  * API >= 1
 
 returns an array of all pads this author contributed to
 
-*Example returns:*
+_Example returns:_
+
   * `{code: 0, message:"ok", data: {padIDs: ["g.s8oes9dhwrvt0zif$test", "g.s8oejklhwrvt0zif$foo"]}}`
   * `{code: 1, message:"authorID does not exist", data: null}`
 
-#### getAuthorName(authorID)
+===== getAuthorName(authorID)
  * API >= 1.1
 
 Returns the Author Name of the author
 
-*Example returns:*
+_Example returns:_
+
   * `{code: 0, message:"ok", data: {authorName: "John McLear"}}`
 
 -> can't be deleted cause this would involve scanning all the pads where this author was
 
-### Session
+==== Session
 Sessions can be created between a group and an author. This allows an author to access more than one group. The sessionID will be set as a cookie to the client and is valid until a certain date. The session cookie can also contain multiple comma-separated sessionIDs, allowing a user to edit pads in different groups at the same time. Only users with a valid session for this group, can access group pads. You can create a session after you authenticated the user at your web application, to give them access to the pads. You should save the sessionID of this session and delete it after the user logged out.
 
-#### createSession(groupID, authorID, validUntil)
+===== createSession(groupID, authorID, validUntil)
  * API >= 1
 
 creates a new session. validUntil is an unix timestamp in seconds
 
-*Example returns:*
+_Example returns:_
+
   * `{code: 0, message:"ok", data: {sessionID: "s.s8oes9dhwrvt0zif"}}`
   * `{code: 1, message:"groupID doesn't exist", data: null}`
   * `{code: 1, message:"authorID doesn't exist", data: null}`
   * `{code: 1, message:"validUntil is in the past", data: null}`
 
-#### deleteSession(sessionID)
+===== deleteSession(sessionID)
  * API >= 1
 
 deletes a session
 
-*Example returns:*
+_Example returns:_
+
   * `{code: 0, message:"ok", data: null}`
   * `{code: 1, message:"sessionID does not exist", data: null}`
 
-#### getSessionInfo(sessionID)
+===== getSessionInfo(sessionID)
  * API >= 1
 
 returns information about a session
 
-*Example returns:*
+_Example returns:_
+
   * `{code: 0, message:"ok", data: {authorID: "a.s8oes9dhwrvt0zif", groupID: g.s8oes9dhwrvt0zif, validUntil: 1312201246}}`
   * `{code: 1, message:"sessionID does not exist", data: null}`
 
-#### listSessionsOfGroup(groupID)
+===== listSessionsOfGroup(groupID)
  * API >= 1
 
 returns all sessions of a group
 
-*Example returns:*
+_Example returns:_
+
   * `{"code":0,"message":"ok","data":{"s.oxf2ras6lvhv2132":{"groupID":"g.s8oes9dhwrvt0zif","authorID":"a.akf8finncvomlqva","validUntil":2312905480}}}`
   * `{code: 1, message:"groupID does not exist", data: null}`
 
-#### listSessionsOfAuthor(authorID)
+===== listSessionsOfAuthor(authorID)
  * API >= 1
 
 returns all sessions of an author
 
-*Example returns:*
+_Example returns:_
+
   * `{"code":0,"message":"ok","data":{"s.oxf2ras6lvhv2132":{"groupID":"g.s8oes9dhwrvt0zif","authorID":"a.akf8finncvomlqva","validUntil":2312905480}}}`
   * `{code: 1, message:"authorID does not exist", data: null}`
 
-### Pad Content
+==== Pad Content
 
 Pad content can be updated and retrieved through the API
 
-#### getText(padID, [rev])
+===== getText(padID, [rev])
  * API >= 1
 
 returns the text of a pad
 
-*Example returns:*
+_Example returns:_
+
   * `{code: 0, message:"ok", data: {text:"Welcome Text"}}`
   * `{code: 1, message:"padID does not exist", data: null}`
 
-#### setText(padID, text, [authorId])
+===== setText(padID, text, [authorId])
  * API >= 1
  * `authorId` in API >= 1.3.0
 
@@ -302,12 +325,13 @@ Sets the text of a pad.
 
 If your text is long (>8 KB), please invoke via POST and include `text` parameter in the body of the request, not in the URL (since Etherpad **1.8**).
 
-*Example returns:*
+_Example returns:_
+
   * `{code: 0, message:"ok", data: null}`
   * `{code: 1, message:"padID does not exist", data: null}`
   * `{code: 1, message:"text too long", data: null}`
 
-#### appendText(padID, text, [authorId])
+===== appendText(padID, text, [authorId])
  * API >= 1.2.13
  * `authorId` in API >= 1.3.0
 
@@ -315,21 +339,23 @@ Appends text to a pad.
 
 If your text is long (>8 KB), please invoke via POST and include `text` parameter in the body of the request, not in the URL (since Etherpad **1.8**).
 
-*Example returns:*
+_Example returns:_
+
   * `{code: 0, message:"ok", data: null}`
   * `{code: 1, message:"padID does not exist", data: null}`
   * `{code: 1, message:"text too long", data: null}`
 
-#### getHTML(padID, [rev])
+===== getHTML(padID, [rev])
  * API >= 1
 
 returns the text of a pad formatted as HTML
 
-*Example returns:*
+_Example returns:_
+
   * `{code: 0, message:"ok", data: {html:"Welcome Text<br>More Text"}}`
   * `{code: 1, message:"padID does not exist", data: null}`
 
-#### setHTML(padID, html, [authorId])
+===== setHTML(padID, html, [authorId])
  * API >= 1
  * `authorId` in API >= 1.3.0
 
@@ -337,16 +363,18 @@ sets the text of a pad based on HTML, HTML must be well-formed. Malformed HTML w
 
 If `html` is long (>8 KB), please invoke via POST and include `html` parameter in the body of the request, not in the URL (since Etherpad **1.8**).
 
-*Example returns:*
+_Example returns:_
+
   * `{code: 0, message:"ok", data: null}`
   * `{code: 1, message:"padID does not exist", data: null}`
 
-#### getAttributePool(padID)
+===== getAttributePool(padID)
  * API >= 1.2.8
 
 returns the attribute pool of a pad
 
-*Example returns:*
+_Example returns:_
+
   * `{ "code":0,
        "message":"ok",
        "data": {
@@ -369,12 +397,13 @@ returns the attribute pool of a pad
      }`
   * `{"code":1,"message":"padID does not exist","data":null}`
 
-#### getRevisionChangeset(padID, [rev])
+===== getRevisionChangeset(padID, [rev])
  * API >= 1.2.8
 
 get the changeset at a given revision, or last revision if 'rev' is not defined.
 
-*Example returns:*
+_Example returns:_
+
   * `{ "code" : 0,
        "message" : "ok",
        "data" : "Z:1>6b|5+6b$Welcome to Etherpad!\n\nThis pad text is synchronized as you type, so that everyone viewing this page sees the same text. This allows you to collaborate seamlessly on documents!\n\nGet involved with Etherpad at https://etherpad.org\n"
@@ -382,27 +411,30 @@ get the changeset at a given revision, or last revision if 'rev' is not defined.
   * `{"code":1,"message":"padID does not exist","data":null}`
   * `{"code":1,"message":"rev is higher than the head revision of the pad","data":null}`
 
-#### createDiffHTML(padID, startRev, endRev)
+===== createDiffHTML(padID, startRev, endRev)
  * API >= 1.2.7
 
 returns an object of diffs from 2 points in a pad
 
-*Example returns:*
+_Example returns:_
+
   * `{"code":0,"message":"ok","data":{"html":"<style>\n.authora_HKIv23mEbachFYfH {background-color: #a979d9}\n.authora_n4gEeMLsv1GivNeh {background-color: #a9b5d9}\n.removed {text-decoration: line-through; -ms-filter:'progid:DXImageTransform.Microsoft.Alpha(Opacity=80)'; filter: alpha(opacity=80); opacity: 0.8; }\n</style>Welcome to Etherpad!<br><br>This pad text is synchronized as you type, so that everyone viewing this page sees the same text. This allows you to collaborate seamlessly on documents!<br><br>Get involved with Etherpad at <a href=\"http&#x3a;&#x2F;&#x2F;etherpad&#x2e;org\">http:&#x2F;&#x2F;etherpad.org</a><br><span class=\"authora_HKIv23mEbachFYfH\">aw</span><br><br>","authors":["a.HKIv23mEbachFYfH",""]}}`
   * `{"code":4,"message":"no or wrong API Key","data":null}`
 
-#### restoreRevision(padId, rev, [authorId])
+===== restoreRevision(padId, rev, [authorId])
  * API >= 1.2.11
  * `authorId` in API >= 1.3.0
 
 Restores revision from past as new changeset
 
-*Example returns:*
+_Example returns:_
+
   * {code:0, message:"ok", data:null}
   * {code: 1, message:"padID does not exist", data: null}
 
-### Chat
-#### getChatHistory(padID, [start, end])
+==== Chat
+
+===== getChatHistory(padID, [start, end])
  * API >= 1.2.7
 
 returns
@@ -411,230 +443,251 @@ returns
 * the whole chat history, when no extra parameters are given
 
 
-*Example returns:*
+_Example returns:_
 
 * `{"code":0,"message":"ok","data":{"messages":[{"text":"foo","userId":"a.foo","time":1359199533759,"userName":"test"},{"text":"bar","userId":"a.foo","time":1359199534622,"userName":"test"}]}}`
 * `{code: 1, message:"start is higher or equal to the current chatHead", data: null}`
 * `{code: 1, message:"padID does not exist", data: null}`
 
-#### getChatHead(padID)
+===== getChatHead(padID)
  * API >= 1.2.7
 
 returns the chatHead (last number of the last chat-message) of the pad
 
 
-*Example returns:*
+_Example returns:_
 
 * `{code: 0, message:"ok", data: {chatHead: 42}}`
 * `{code: 1, message:"padID does not exist", data: null}`
 
-#### appendChatMessage(padID, text, authorID [, time])
+===== appendChatMessage(padID, text, authorID [, time])
  * API >= 1.2.12
 
 creates a chat message, saves it to the database and sends it to all connected clients of this pad
 
 
-*Example returns:*
+_Example returns:_
 
 * `{code: 0, message:"ok", data: null}`
 * `{code: 1, message:"text is no string", data: null}`
 
-### Pad
+=== Pad
 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.
 
-#### createPad(padID, [text], [authorId])
+==== createPad(padID, [text], [authorId])
  * API >= 1
  * `authorId` in API >= 1.3.0
 
 creates a new (non-group) pad.  Note that if you need to create a group Pad, you should call **createGroupPad**.
 You get an error message if you use one of the following characters in the padID: "/", "?", "&" or "#".
 
-*Example returns:*
+_Example returns:_
+
   * `{code: 0, message:"ok", data: null}`
   * `{code: 1, message:"padID does already exist", data: null}`
   * `{code: 1, message:"malformed padID: Remove special characters", data: null}`
 
-#### getRevisionsCount(padID)
+==== getRevisionsCount(padID)
  * API >= 1
 
 returns the number of revisions of this pad
 
-*Example returns:*
+_Example returns:_
+
   * `{code: 0, message:"ok", data: {revisions: 56}}`
   * `{code: 1, message:"padID does not exist", data: null}`
 
-#### getSavedRevisionsCount(padID)
+==== getSavedRevisionsCount(padID)
  * API >= 1.2.11
 
 returns the number of saved revisions of this pad
 
-*Example returns:*
+_Example returns:_
+
   * `{code: 0, message:"ok", data: {savedRevisions: 42}}`
   * `{code: 1, message:"padID does not exist", data: null}`
 
-#### listSavedRevisions(padID)
+==== listSavedRevisions(padID)
  * API >= 1.2.11
 
 returns the list of saved revisions of this pad
 
-*Example returns:*
+_Example returns:_
+
   * `{code: 0, message:"ok", data: {savedRevisions: [2, 42, 1337]}}`
   * `{code: 1, message:"padID does not exist", data: null}`
 
-#### saveRevision(padID [, rev])
+==== saveRevision(padID [, rev])
  * API >= 1.2.11
 
 saves a revision
 
-*Example returns:*
+_Example returns:_
+
   * `{code: 0, message:"ok", data: null}`
   * `{code: 1, message:"padID does not exist", data: null}`
 
-#### padUsersCount(padID)
+==== padUsersCount(padID)
  * API >= 1
 
 returns the number of user that are currently editing this pad
 
-*Example returns:*
+_Example returns:_
+
   * `{code: 0, message:"ok", data: {padUsersCount: 5}}`
 
-#### padUsers(padID)
+==== padUsers(padID)
  * API >= 1.1
 
 returns the list of users that are currently editing this pad
 
-*Example returns:*
+_Example returns:_
+
   * `{code: 0, message:"ok", data: {padUsers: [{colorId:"#c1a9d9","name":"username1","timestamp":1345228793126,"id":"a.n4gEeMLsvg12452n"},{"colorId":"#d9a9cd","name":"Hmmm","timestamp":1345228796042,"id":"a.n4gEeMLsvg12452n"}]}}`
   * `{code: 0, message:"ok", data: {padUsers: []}}`
 
-#### deletePad(padID)
+==== deletePad(padID)
  * API >= 1
 
 deletes a pad
 
-*Example returns:*
+_Example returns:_
+
   * `{code: 0, message:"ok", data: null}`
   * `{code: 1, message:"padID does not exist", data: null}`
 
-#### copyPad(sourceID, destinationID[, force=false])
+==== copyPad(sourceID, destinationID[, force=false])
  * API >= 1.2.8
 
 copies a pad with full history and chat. If force is true and the destination pad exists, it will be overwritten.
 
-*Example returns:*
+_Example returns:_
+
   * `{code: 0, message:"ok", data: null}`
   * `{code: 1, message:"padID does not exist", data: null}`
 
-#### copyPadWithoutHistory(sourceID, destinationID, [force=false], [authorId])
+==== copyPadWithoutHistory(sourceID, destinationID, [force=false], [authorId])
 * API >= 1.2.15
  * `authorId` in API >= 1.3.0
 
 copies a pad without copying the history and chat. If force is true and the destination pad exists, it will be overwritten.
 Note that all the revisions will be lost! In most of the cases one should use `copyPad` API instead.
 
-*Example returns:*
+_Example returns:_
+
 * `{code: 0, message:"ok", data: null}`
 * `{code: 1, message:"padID does not exist", data: null}`
 
-#### movePad(sourceID, destinationID[, force=false])
+==== movePad(sourceID, destinationID[, force=false])
  * API >= 1.2.8
 
 moves a pad. If force is true and the destination pad exists, it will be overwritten.
 
-*Example returns:*
+_Example returns:_
+
   * `{code: 0, message:"ok", data: null}`
   * `{code: 1, message:"padID does not exist", data: null}`
 
-#### getReadOnlyID(padID)
+==== getReadOnlyID(padID)
  * API >= 1
 
 returns the read only link of a pad
 
-*Example returns:*
+_Example returns:_
+
   * `{code: 0, message:"ok", data: {readOnlyID: "r.s8oes9dhwrvt0zif"}}`
   * `{code: 1, message:"padID does not exist", data: null}`
 
-#### getPadID(readOnlyID)
+==== getPadID(readOnlyID)
  * API >= 1.2.10
 
 returns the id of a pad which is assigned to the readOnlyID
 
-*Example returns:*
+_Example returns:_
+
   * `{code: 0, message:"ok", data: {padID: "p.s8oes9dhwrvt0zif"}}`
   * `{code: 1, message:"padID does not exist", data: null}`
 
-#### setPublicStatus(padID, publicStatus)
+==== setPublicStatus(padID, publicStatus)
  * API >= 1
 
 sets a boolean for the public status of a group pad
 
-*Example returns:*
+_Example returns:_
+
   * `{code: 0, message:"ok", data: null}`
   * `{code: 1, message:"padID does not exist", data: null}`
   * `{code: 1, message:"You can only get/set the publicStatus of pads that belong to a group", data: null}`
 
-#### getPublicStatus(padID)
+==== getPublicStatus(padID)
  * API >= 1
 
 return true of false
 
-*Example returns:*
+_Example returns:_
+
   * `{code: 0, message:"ok", data: {publicStatus: true}}`
   * `{code: 1, message:"padID does not exist", data: null}`
   * `{code: 1, message:"You can only get/set the publicStatus of pads that belong to a group", data: null}`
 
-#### listAuthorsOfPad(padID)
+==== listAuthorsOfPad(padID)
  * API >= 1
 
 returns an array of authors who contributed to this pad
 
-*Example returns:*
+_Example returns:_
+
   * `{code: 0, message:"ok", data: {authorIDs : ["a.s8oes9dhwrvt0zif", "a.akf8finncvomlqva"]}`
   * `{code: 1, message:"padID does not exist", data: null}`
 
-#### getLastEdited(padID)
+==== getLastEdited(padID)
  * API >= 1
 
 returns the timestamp of the last revision of the pad
 
-*Example returns:*
+_Example returns:_
+
   * `{code: 0, message:"ok", data: {lastEdited: 1340815946602}}`
   * `{code: 1, message:"padID does not exist", data: null}`
 
-#### sendClientsMessage(padID, msg)
+==== sendClientsMessage(padID, msg)
  * API >= 1.1
 
 sends a custom message of type `msg` to the pad
 
-*Example returns:*
+_Example returns:_
+
   * `{code: 0, message:"ok", data: {}}`
   * `{code: 1, message:"padID does not exist", data: null}`
 
-#### checkToken()
+==== checkToken()
  * API >= 1.2
 
 returns ok when the current api token is valid
 
-*Example returns:*
+_Example returns:_
+
   * `{"code":0,"message":"ok","data":null}`
   * `{"code":4,"message":"no or wrong API Key","data":null}`
 
-### Pads
+=== Pads
 
-#### listAllPads()
+==== listAllPads()
  * API >= 1.2.1
 
 lists all pads on this epl instance
 
-*Example returns:*
+_Example returns:_
+
  * `{code: 0, message:"ok", data: {padIDs: ["testPad", "thePadsOfTheOthers"]}}`
 
-### Global
+==== Global
 
-#### getStats()
+===== getStats()
  *  API >= 1.2.14
 
 get stats of the etherpad instance
 
-*Example returns*
+_Example returns_:
+
  * `{"code":0,"message":"ok","data":{"totalPads":3,"totalSessions": 2,"totalActivePads": 1}}`

doc/api/pluginfw.adoc

@@ -1,22 +1,22 @@
-# Plugin Framework
+== Plugin Framework
 
 `require("ep_etherpad-lite/static/js/plugingfw/plugins")`
 
-## plugins.update
+=== plugins.update
 
 `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)
 
-## hooks.callAll
+=== hooks.callAll
 
 `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}`.
 
-## hooks.aCallAll
+=== hooks.aCallAll
 
 ?
 
-## ...
+=== ...

doc/api/toolbar.adoc

@@ -1,7 +1,7 @@
-# Toolbar controller
+== Toolbar controller
 src/node/utils/toolbar.js
 
-## button(opts)
+=== button(opts)
  * {Object} `opts`
    * `command` - this command fill be fired on the editbar on click
    * `localizationId` - will be set as `data-l10-id`
@@ -10,25 +10,28 @@ src/node/utils/toolbar.js
 Returns: {Button}
 
 Example:
-```
+
+[source, javascript]
+----
 var orderedlist = toolbar.button({
   command: "insertorderedlist",
   localizationId: "pad.toolbar.ol.title",
   class: "buttonicon buttonicon-insertorderedlist"
 })
-```
+----
 
 You can also create buttons with text:
 
-```
+[source, javascript]
+----
 var myButton = toolbar.button({
   command: "myButton",
   localizationId: "myPlugin.toolbar.myButton",
   class: "buttontext"
 })
-```
+----
 
-## selectButton(opts)
+=== selectButton(opts)
  * {Object} `opts`
    * `id` - id of the menu item
    * `selectId` - id of the select element
@@ -36,11 +39,11 @@ var myButton = toolbar.button({
 
 Returns: {SelectButton}
 
-## SelectButton.addOption(value, text, attributes)
+=== SelectButton.addOption(value, text, attributes)
  * {String} value - The value of this option
  * {String} text - the label text used for this option
  * {Object} attributes - any additional html attributes go here (e.g. `data-l10n-id`)
 
-## registerButton(name, item)
+=== registerButton(name, item)
   * {String} name - used to reference the item in the toolbar config in settings.json
   * {Button|SelectButton} item - the button to add

doc/assets/style.css

@@ -12,11 +12,27 @@ a {
   color: #555;
 }
 
-h1 {
+h1,h2 {
   color: #44b492;
   line-height:100%;
 }
 
+h2 {
+  font-size: 48px ;
+}
+
+h3 {
+  font-size: 1.8rem;
+}
+
+h4{
+  font-size: 1.5rem;
+}
+
+h5{
+  font-size: 1.2rem;
+}
+
 a:hover {
   color: #44b492;
 }

doc/cookies.adoc

@@ -0,0 +1,74 @@
+== Cookies
+Cookies used by Etherpad.
+
+[cols="1,1,1,1,1,1,1,1"]
+|===
+
+| Name
+| Sample value
+| Domain
+| Path
+| Expires/max-age
+| Http-only
+| Secure
+|  Usage description
+|express_sid
+| s%3A7yCNjRmTW8ylGQ53I2IhOwYF9...
+| example.org
+|/
+| Session
+| true
+| true
+| Session ID of the https://expressjs.com[Express web framework]. When Etherpad is behind a reverse proxy, and an administrator wants to use session stickiness, he may use this cookie. If you are behind a reverse proxy, please remember to set `trustProxy: true` in `settings.json`. Set in [webaccess.js#L131](https://github.com/ether/etherpad-lite/blob/01497aa399690e44393e91c19917d11d025df71b/src/node/hooks/express/webaccess.js#L131).
+
+
+|language
+| en
+| example.org
+| /
+| Session
+| false
+| true
+| The language of the UI (e.g.: `en-GB`, `it`). Set in [pad_editor.js#L111](https://github.com/ether/etherpad-lite/blob/01497aa399690e44393e91c19917d11d025df71b/src/static/js/pad_editor.js#L111).
+
+
+|prefs / prefsHttp
+| %7B%22epThemesExtTheme%22...
+| example.org
+| /p
+| year 3000
+| false
+| true
+| Client-side preferences (e.g.: font family, chat always visible, show authorship colors, ...). Set in [pad_cookie.js#L49](https://github.com/ether/etherpad-lite/blob/01497aa399690e44393e91c19917d11d025df71b/src/static/js/pad_cookie.js#L49). `prefs` is used if Etherpad is accessed over HTTPS, `prefsHttp` if accessed over HTTP. For more info see https://github.com/ether/etherpad-lite/issues/3179.
+
+
+
+|token
+| t.tFzkihhhBf4xKEpCK3PU
+| example.org
+| /
+| 60 days
+| false
+| true
+| A random token representing the author, of the form `t.randomstring_of_lenght_20`. The random string is generated by the client, at (https://github.com/ether/etherpad-lite/blob/01497aa399690e44393e91c19917d11d025df71b/src/static/js/pad.js#L55-L66[pad.js#L55-L66]). This cookie is always set by the client (at (https://github.com/ether/etherpad-lite/blob/01497aa399690e44393e91c19917d11d025df71b/src/static/js/pad.js#L153-L158[pad.js#L153-L158])) without any solicitation from the server. It is used for all the pads accessed via the web UI (not used for the HTTP API). On the server side, its value is accessed at [SecurityManager.js#L33](https://github.com/ether/etherpad-lite/blob/01497aa399690e44393e91c19917d11d025df71b/src/node/db/SecurityManager.js#L33).
+|===
+
+For more info, visit the related discussion at https://github.com/ether/etherpad-lite/issues/3563.
+
+Etherpad HTTP API clients may make use (if they choose so) to send another cookie:
+
+
+[cols="1,1,1"]
+|===
+
+| Name
+| Sample value
+| Domain
+| Usage description
+
+
+| sessionID
+| s.1c70968b333b25476a2c7bdd0e0bed17
+| example.org
+| Sessions can be created between a group and an author. This allows an author to access more than one group. The sessionID will be set as a cookie to the client and is valid until a certain date. The session cookie can also contain multiple comma-separated sessionIDs, allowing a user to edit pads in different groups at the same time. More info - https://github.com/ether/etherpad-lite/blob/develop/doc/api/http_api.md#session
+|===

doc/cookies.md

@@ -1,18 +0,0 @@
-# Cookies
-
-Cookies used by Etherpad.
-
-| Name            | Sample value                       | Domain      | Path | Expires/max-age | Http-only| Secure |  Usage description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-|-----------------|------------------------------------|-------------|------|-----------------|----------|--------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-|express_sid      | s%3A7yCNjRmTW8ylGQ53I2IhOwYF9...   | example.org | /    | Session         | true     | true   | Session ID of the [Express web framework](https://expressjs.com). When Etherpad is behind a reverse proxy, and an administrator wants to use session stickiness, he may use this cookie. If you are behind a reverse proxy, please remember to set `trustProxy: true` in `settings.json`. Set in [webaccess.js#L131](https://github.com/ether/etherpad-lite/blob/01497aa399690e44393e91c19917d11d025df71b/src/node/hooks/express/webaccess.js#L131).                                                                                                                                                                                                                                                                                                                                      |
-|language         | en                                 | example.org | /    | Session         | false    | true   | The language of the UI (e.g.: `en-GB`, `it`). Set in [pad_editor.js#L111](https://github.com/ether/etherpad-lite/blob/01497aa399690e44393e91c19917d11d025df71b/src/static/js/pad_editor.js#L111).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-|prefs / prefsHttp| %7B%22epThemesExtTheme%22...       | example.org | /p   | year 3000       | false    | true   | Client-side preferences (e.g.: font family, chat always visible, show authorship colors, ...). Set in [pad_cookie.js#L49](https://github.com/ether/etherpad-lite/blob/01497aa399690e44393e91c19917d11d025df71b/src/static/js/pad_cookie.js#L49). `prefs` is used if Etherpad is accessed over HTTPS, `prefsHttp` if accessed over HTTP. For more info see https://github.com/ether/etherpad-lite/issues/3179.                                                                                                                                                                                                                                                                                                                                                                             |
-|token            | t.tFzkihhhBf4xKEpCK3PU             | example.org | /    | 60 days         | false    | true   | A random token representing the author, of the form `t.randomstring_of_lenght_20`. The random string is generated by the client, at ([pad.js#L55-L66](https://github.com/ether/etherpad-lite/blob/01497aa399690e44393e91c19917d11d025df71b/src/static/js/pad.js#L55-L66)). This cookie is always set by the client (at [pad.js#L153-L158](https://github.com/ether/etherpad-lite/blob/01497aa399690e44393e91c19917d11d025df71b/src/static/js/pad.js#L153-L158)) without any solicitation from the server. It is used for all the pads accessed via the web UI (not used for the HTTP API). On the server side, its value is accessed at [SecurityManager.js#L33](https://github.com/ether/etherpad-lite/blob/01497aa399690e44393e91c19917d11d025df71b/src/node/db/SecurityManager.js#L33).|
-
-For more info, visit the related discussion at https://github.com/ether/etherpad-lite/issues/3563.
-
-Etherpad HTTP API clients may make use (if they choose so) to send another cookie:
-
-| Name            | Sample value                       | Domain      | Usage description                                                                                                                                                                                                                                                                                                                                                                                                                          |
-|-----------------|------------------------------------|-------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-|sessionID        | s.1c70968b333b25476a2c7bdd0e0bed17 | example.org | Sessions can be created between a group and an author. This allows an author to access more than one group. The sessionID will be set as a cookie to the client and is valid until a certain date. The session cookie can also contain multiple comma-separated sessionIDs, allowing a user to edit pads in different groups at the same time. More info - https://github.com/ether/etherpad-lite/blob/develop/doc/api/http_api.md#session |

doc/database.adoc

@@ -1,11 +1,11 @@
-# Database structure
+== Database structure
 
-## Keys and their values
+=== Keys and their values
 
-### groups
+==== groups
 A list of all existing groups (a JSON object with groupIDs as keys and `1` as values).
 
-### pad:$PADID
+==== pad:$PADID
 Contains all information about pads
 
 * **atext** - the latest attributed text
@@ -15,7 +15,7 @@ Contains all information about pads
 * **public** - flag that disables security for this pad
 * **passwordHash** - string that contains a salted sha512 sum of this pad's password
 
-### pad:$PADID:revs:$REVNUM
+==== pad:$PADID:revs:$REVNUM
 Saves a revision $REVNUM of pad $PADID
 
 * **meta**
@@ -23,45 +23,50 @@ Saves a revision $REVNUM of pad $PADID
   * **timestamp** - the timestamp of when this revision was created
 * **changeset** - the changeset of this revision
 
-### pad:$PADID:chat:$CHATNUM
+==== pad:$PADID:chat:$CHATNUM
 Saves a chat entry with num $CHATNUM of pad $PADID
 
 * **text** - the text of this chat entry
 * **userId** - the authorID of this chat entry
 * **time** - the timestamp of this chat entry
 
-### pad2readonly:$PADID
+==== pad2readonly:$PADID
 Translates a padID to a readonlyID
-### readonly2pad:$READONLYID
+
+==== readonly2pad:$READONLYID
 Translates a readonlyID to a padID
-### token2author:$TOKENID
+
+==== token2author:$TOKENID
 Translates a token to an authorID
-### globalAuthor:$AUTHORID
+
+==== globalAuthor:$AUTHORID
 Information about an author
 
 * **name** - the name of this author as shown in the pad
 * **colorID** - the colorID of this author as shown in the pad
 
-### mapper2group:$MAPPER
+==== mapper2group:$MAPPER
 Maps an external application identifier to an internal group
-### mapper2author:$MAPPER
+
+==== mapper2author:$MAPPER
 Maps an external application identifier to an internal author
-### group:$GROUPID
+
+==== group:$GROUPID
 a group of pads
 
 * **pads** - object with pad names in it, values are 1
-### session:$SESSIONID
+==== session:$SESSIONID
 a session between an author and a group
 
 * **groupID** - the groupID the session belongs too
 * **authorID** - the authorID the session belongs too
 * **validUntil** - the timestamp until this session is valid
 
-### author2sessions:$AUTHORID
+==== author2sessions:$AUTHORID
 saves the sessions of an author
 
 * **sessionsIDs** - object with sessionIDs in it, values are 1
 
-### group2sessions:$GROUPID
+==== group2sessions:$GROUPID
 
 * **sessionsIDs** - object with sessionIDs in it, values are 1

doc/docker.adoc

@@ -0,0 +1,534 @@
+== Docker
+
+The official Docker image is available on https://hub.docker.com/r/etherpad/etherpad.
+
+=== Downloading from Docker Hub
+If you are ok downloading a https://hub.docker.com/r/etherpad/etherpad[prebuilt image from Docker Hub], these are the commands:
+
+[source, bash]
+----
+# gets the latest published version
+docker pull etherpad/etherpad
+
+# gets a specific version
+docker pull etherpad/etherpad:1.8.0
+----
+
+=== Build a personalized container
+
+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.
+
+==== Rebuilding with custom settings
+Edit `<BASEDIR>/settings.json.docker` at your will. When rebuilding the image, this file will be copied inside your image and renamed to `settings.json`.
+
+**Each configuration parameter can also be set via an environment variable**, using the syntax `"${ENV_VAR}"` or `"${ENV_VAR:default_value}"`. For details, refer to `settings.json.template`.
+
+==== Rebuilding including some plugins
+If you want to install some plugins in your container, it is sufficient to list them in the ETHERPAD_PLUGINS build variable.
+The variable value has to be a space separated, double quoted list of plugin names (see examples).
+
+Some plugins will need personalized settings. Just refer to the previous section, and include them in your custom `settings.json.docker`.
+
+==== Rebuilding including export functionality for DOC/PDF/ODT
+
+If you want to be able to export your pads to DOC/PDF/ODT files, you can install
+either Abiword or Libreoffice via setting a build variable.
+
+===== Via Abiword
+
+For installing Abiword, set the `INSTALL_ABIWORD` build variable to any value.
+
+Also, you will need to configure the path to the abiword executable
+via setting the `abiword` property in `<BASEDIR>/settings.json.docker` to
+`/usr/bin/abiword` or via setting the environment variable  `ABIWORD` to
+`/usr/bin/abiword`.
+
+===== Via Libreoffice
+
+For installing Libreoffice instead, set the `INSTALL_SOFFICE` build variable
+to any value.
+
+Also, you will need to configure the path to the libreoffice executable
+via setting the `soffice` property in `<BASEDIR>/settings.json.docker` to
+`/usr/bin/soffice` or via setting the environment variable  `SOFFICE` to
+`/usr/bin/soffice`.
+
+==== Examples
+
+Build a Docker image from the currently checked-out code:
+
+[source,bash]
+----
+docker build --tag <YOUR_USERNAME>/etherpad .
+----
+
+Include two plugins in the container:
+
+[source,bash]
+----
+docker build --build-arg ETHERPAD_PLUGINS="ep_comments_page ep_author_neat" --tag <YOUR_USERNAME>/etherpad .
+----
+
+=== Running your instance:
+
+To run your instance:
+
+[source,bash]
+----
+docker run --detach --publish <DESIRED_PORT>:9001 <YOUR_USERNAME>/etherpad
+----
+
+And point your browser to `http://<YOUR_IP>:<DESIRED_PORT>`
+
+=== Options available by default
+
+The `settings.json.docker` available by default allows to control almost every setting via environment variables.
+
+==== General
+
+[cols="1,1,1"]
+|===
+| Variable
+| Description
+| Default
+| `TITLE`
+| The name of the instance
+| `Etherpad`
+
+| `FAVICON`
+| favicon default name, or a fully specified URL to your own favicon
+| `favicon.ico`
+| `DEFAULT_PAD_TEXT`
+| The default text of a pad
+| `Welcome to Etherpad! This pad text is synchronized as you type, so that everyone viewing this page sees the same text. This allows you to collaborate seamlessly on documents! Get involved with Etherpad at https://etherpad.org`
+
+| `IP`
+| IP which etherpad should bind at. Change to `::` for IPv6
+| `0.0.0.0`
+| `PORT`
+| port which etherpad should bind at
+| `9001`
+| `ADMIN_PASSWORD`
+| the password for the `admin` user (leave unspecified if you do not want to create it)
+|
+| `USER_PASSWORD`
+| the password for the first user `user` (leave unspecified if you do not want to create it)
+|
+|===
+
+==== Database
+
+[cols="1,1,1"]
+|===
+| Variable
+| Description
+| Default
+
+| `DB_TYPE`     | a database supported by https://www.npmjs.com/package/ueberdb2 | not set, thus will fall back to `DirtyDB` (please choose one instead)
+| `DB_HOST`     | the host of the database
+|
+
+| `DB_PORT`
+| the port of the database
+|
+
+| `DB_NAME`
+| the database name
+|
+
+| `DB_USER`
+| a database user with sufficient permissions to create tables
+|
+
+| `DB_PASS`
+| the password for the database username
+|
+
+| `DB_CHARSET`
+| the character set for the tables (only required for MySQL)
+|
+
+| `DB_FILENAME`
+| in case `DB_TYPE` is `DirtyDB` or `sqlite`, the database file.
+| `var/dirty.db`, `var/etherpad.sq3`
+|===
+
+If your database needs additional settings, you will have to use a personalized `settings.json.docker` and rebuild the container (or otherwise put the updated `settings.json` inside your image).
+
+
+==== Pad Options
+
+[cols="1,1,1"]
+|===
+
+| Variable
+| Description
+| Default
+
+
+| `PAD_OPTIONS_NO_COLORS`
+|
+| `false`
+
+
+| `PAD_OPTIONS_SHOW_CONTROLS`
+|
+| `true`
+
+| `PAD_OPTIONS_SHOW_CHAT`
+|
+| `true`
+
+| `PAD_OPTIONS_SHOW_LINE_NUMBERS`
+|
+| `true`
+
+| `PAD_OPTIONS_USE_MONOSPACE_FONT`
+|
+| `false`
+
+| `PAD_OPTIONS_USER_NAME`
+|
+| `null`
+
+| `PAD_OPTIONS_USER_COLOR`
+|
+| `null`
+
+| `PAD_OPTIONS_RTL`
+|
+| `false`
+
+| `PAD_OPTIONS_ALWAYS_SHOW_CHAT`
+|
+| `false`
+
+| `PAD_OPTIONS_CHAT_AND_USERS`
+|
+|  `false`
+
+| `PAD_OPTIONS_LANG`
+|
+| `null`
+|===
+
+==== Shortcuts
+
+[cols="1,1,1"]
+|===
+| Variable
+| Description
+| Default
+
+
+| `PAD_SHORTCUTS_ENABLED_ALT_F9`
+| focus on the File Menu and/or editbar
+| `true`
+
+| `PAD_SHORTCUTS_ENABLED_ALT_C`
+| focus on the Chat window
+| `true`
+
+| `PAD_SHORTCUTS_ENABLED_CMD_S`
+| save a revision
+| `true`
+
+| `PAD_SHORTCUTS_ENABLED_CMD_Z`
+| undo/redo
+| `true`
+
+| `PAD_SHORTCUTS_ENABLED_CMD_Y`
+| redo
+| `true`
+
+| `PAD_SHORTCUTS_ENABLED_CMD_I`
+| italic
+| `true`
+
+| `PAD_SHORTCUTS_ENABLED_CMD_B`
+| bold
+| `true`
+
+| `PAD_SHORTCUTS_ENABLED_CMD_U`
+| underline
+| `true`
+
+| `PAD_SHORTCUTS_ENABLED_CMD_H`
+| backspace
+| `true`
+
+| `PAD_SHORTCUTS_ENABLED_CMD_5`
+| strike through
+| `true`
+
+| `PAD_SHORTCUTS_ENABLED_CMD_SHIFT_1`
+| ordered list
+| `true`
+
+| `PAD_SHORTCUTS_ENABLED_CMD_SHIFT_2`
+| shows a gritter popup showing a line author
+| `true`
+
+| `PAD_SHORTCUTS_ENABLED_CMD_SHIFT_L`
+| unordered list
+| `true`
+
+| `PAD_SHORTCUTS_ENABLED_CMD_SHIFT_N`
+| ordered list
+|`true`
+
+| `PAD_SHORTCUTS_ENABLED_CMD_SHIFT_C`
+| clear authorship
+| `true`
+
+| `PAD_SHORTCUTS_ENABLED_DELETE`
+|
+| `true`
+
+
+| `PAD_SHORTCUTS_ENABLED_RETURN`
+|
+| `true`
+
+| `PAD_SHORTCUTS_ENABLED_ESC`
+| in mozilla versions 14-19 avoid reconnecting pad
+| `true`
+
+| `PAD_SHORTCUTS_ENABLED_TAB`
+| indent
+| `true`
+
+| `PAD_SHORTCUTS_ENABLED_CTRL_HOME`
+| scroll to top of pad
+| `true`
+
+| `PAD_SHORTCUTS_ENABLED_PAGE_UP`
+|
+| `true`
+
+| `PAD_SHORTCUTS_ENABLED_PAGE_DOWN`
+|
+| `true`
+|===
+
+==== Skins
+
+You can use the UI skin variants builder at `/p/test#skinvariantsbuilder`
+
+For the colibris skin only, you can choose how to render the three main containers:
+  * toolbar (top menu with icons)
+  * editor (containing the text of the pad)
+  * background (area outside of editor, mostly visible when using page style)
+
+For each of the 3 containers you can choose 4 color combinations:
+   * super-light
+   * light
+   * dark
+   * super-dark
+
+For the editor container, you can also make it full width by adding `full-width-editor` variant (by default editor is rendered as a page, with a max-width of 900px).
+
+[cols="1,1,1"]
+|===
+| Variable
+| Description
+| Default
+
+| `SKIN_NAME`
+| either `no-skin`, `colibris` or an existing directory under `src/static/skins`
+| `colibris`
+
+| `SKIN_VARIANTS`
+| multiple skin variants separated by spaces
+| `super-light-toolbar super-light-editor light-background`
+|===
+
+==== Logging
+
+[cols="1,1,1"]
+|===
+| Variable
+| Description
+| Default
+
+
+| `LOGLEVEL`
+| valid values are `DEBUG`, `INFO`, `WARN` and `ERROR` | `INFO`
+
+| `DISABLE_IP_LOGGING`
+| Privacy: disable IP logging
+| `false`
+|===
+
+==== Advanced
+
+[cols="1,1,1"]
+|===
+| Variable
+| Description
+| Default
+
+| `COOKIE_SAME_SITE`
+| Value of the SameSite cookie property.
+| `"Lax"`
+
+| `COOKIE_SESSION_LIFETIME`
+| How long (ms) a user can be away before they must log in again.
+| `864000000` (10 days)
+
+| `COOKIE_SESSION_REFRESH_INTERVAL`
+| How often (ms) to write the latest cookie expiration time.
+| `86400000` (1 day)
+
+| `SHOW_SETTINGS_IN_ADMIN_PAGE`
+| hide/show the settings.json in admin page
+| `true`
+
+| `TRUST_PROXY`
+| set to `true` if you are using a reverse proxy in front of Etherpad (for example: Traefik for SSL termination via Let's Encrypt). This will affect security and correctness of the logs if not done
+| `false`
+
+| `IMPORT_MAX_FILE_SIZE`
+| maximum allowed file size when importing a pad, in bytes.
+| `52428800` (50 MB)
+
+| `IMPORT_EXPORT_MAX_REQ_PER_IP`
+| maximum number of import/export calls per IP.
+| `10`
+
+| `IMPORT_EXPORT_RATE_LIMIT_WINDOW`
+| the call rate for import/export requests will be estimated in this time window (in milliseconds)
+| `90000`
+
+| `COMMIT_RATE_LIMIT_DURATION`
+| duration of the rate limit window for commits by individual users/IPs (in seconds)                               | `1`
+
+| `COMMIT_RATE_LIMIT_POINTS`
+| maximum number of changes per IP to allow during the rate limit window
+| `10`
+
+| `SUPPRESS_ERRORS_IN_PAD_TEXT`
+| Should we suppress errors from being visible in the default Pad Text?
+| `false
+
+| `REQUIRE_SESSION`
+| If this option is enabled, a user must have a session to access pads. This effectively allows only group pads to be accessed.
+| `false`
+
+| `EDIT_ONLY`
+| Users may edit pads but not create new ones. Pad creation is only via the API. This applies both to group pads and regular pads.
+| `false`
+
+| `MINIFY`
+| If true, all css & js will be minified before sending to the client. This will improve the loading performance massively, but makes it difficult to debug the javascript/css
+| `true`
+
+| `MAX_AGE`
+| How long may clients use served javascript code (in seconds)? Not setting this may cause problems during deployment. Set to 0 to disable caching.
+| `21600` (6 hours)
+
+| `ABIWORD`
+| Absolute path to the Abiword executable. Abiword is needed to get advanced import/export features of pads. Setting it to null disables Abiword and will only allow plain text and HTML import/exports.
+| `null`
+
+| `SOFFICE`
+| This is the absolute path to the soffice executable. LibreOffice can be used in lieu of Abiword to export pads. Setting it to null disables LibreOffice exporting.
+| `null`
+
+| `TIDY_HTML`
+| Path to the Tidy executable. Tidy is used to improve the quality of exported pads. Setting it to null disables Tidy.
+| `null`
+
+| `ALLOW_UNKNOWN_FILE_ENDS`
+| Allow import of file types other than the supported ones: txt, doc, docx, rtf, odt, html & htm
+| `true`
+
+| `REQUIRE_AUTHENTICATION`
+| This setting is used if you require authentication of all users. Note: "/admin" always requires authentication.
+| `false`
+
+| `REQUIRE_AUTHORIZATION`
+| Require authorization by a module, or a user with is_admin set, see below.
+| `false`
+
+| `AUTOMATIC_RECONNECTION_TIMEOUT`
+| Time (in seconds) to automatically reconnect pad when a "Force reconnect" message is shown to user. Set to 0 to disable automatic reconnection.
+| `0`
+
+| `FOCUS_LINE_PERCENTAGE_ABOVE`
+| Percentage of viewport height to be additionally scrolled. e.g. 0.5, to place caret line in the middle of viewport, when user edits a line above of the viewport. Set to 0 to disable extra scrolling
+| `0`
+
+| `FOCUS_LINE_PERCENTAGE_BELOW`
+| Percentage of viewport height to be additionally scrolled. e.g. 0.5, to place caret line in the middle of viewport, when user edits a line below of the viewport. Set to 0 to disable extra scrolling
+| `0`
+
+| `FOCUS_LINE_PERCENTAGE_ARROW_UP`
+| Percentage of viewport height to be additionally scrolled when user presses arrow up in the line of the top of the viewport. Set to 0 to let the scroll to be handled as default by Etherpad
+| `0`
+
+| `FOCUS_LINE_DURATION`
+| Time (in milliseconds) used to animate the scroll transition. Set to 0 to disable animation
+| `0`
+
+| `FOCUS_LINE_CARET_SCROLL`
+| Flag to control if it should scroll when user places the caret in the last line of the viewport
+| `false`
+
+| `SOCKETIO_MAX_HTTP_BUFFER_SIZE`
+| The maximum size (in bytes) of a single message accepted via Socket.IO. If a client sends a larger message, its connection gets closed to prevent DoS (memory exhaustion) attacks.
+| `10000`
+
+| `LOAD_TEST`
+| Allow Load Testing tools to hit the Etherpad Instance. WARNING: this will disable security on the instance.
+| `false`
+
+| `DUMP_ON_UNCLEAN_EXIT`
+| Enable dumping objects preventing a clean exit of Node.js. WARNING: this has a significant performance impact.
+| `false`
+
+| `EXPOSE_VERSION`
+| Expose Etherpad version in the web interface and in the Server http header. Do not enable on production machines.
+| `false`
+|===
+
+==== Examples
+
+Use a Postgres database, no admin user enabled:
+
+[source,bash]
+----
+docker run -d \
+	--name etherpad         \
+	-p 9001:9001            \
+	-e 'DB_TYPE=postgres'   \
+	-e 'DB_HOST=db.local'   \
+	-e 'DB_PORT=4321'       \
+	-e 'DB_NAME=etherpad'   \
+	-e 'DB_USER=dbusername' \
+	-e 'DB_PASS=mypassword' \
+	etherpad/etherpad
+----
+
+Run enabling the administrative user `admin`:
+
+[source,bash]
+----
+docker run -d \
+	--name etherpad \
+	-p 9001:9001 \
+	-e 'ADMIN_PASSWORD=supersecret' \
+	etherpad/etherpad
+----
+
+Run a test instance running DirtyDB on a persistent volume:
+
+[source, bash]
+----
+docker run -d \
+	-v etherpad_data:/opt/etherpad-lite/var \
+	-p 9001:9001 \
+	etherpad/etherpad
+----

doc/docker.md

@@ -1,257 +0,0 @@
-# Docker
-
-The official Docker image is available on https://hub.docker.com/r/etherpad/etherpad.
-
-## Downloading from Docker Hub
-If you are ok downloading a [prebuilt image from Docker Hub](https://hub.docker.com/r/etherpad/etherpad), these are the commands:
-```bash
-# gets the latest published version
-docker pull etherpad/etherpad
-
-# gets a specific version
-docker pull etherpad/etherpad:1.8.0
-```
-
-## Build a personalized container
-
-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.
-
-### Rebuilding with custom settings
-Edit `<BASEDIR>/settings.json.docker` at your will. When rebuilding the image, this file will be copied inside your image and renamed to `settings.json`.
-
-**Each configuration parameter can also be set via an environment variable**, using the syntax `"${ENV_VAR}"` or `"${ENV_VAR:default_value}"`. For details, refer to `settings.json.template`.
-
-### Rebuilding including some plugins
-If you want to install some plugins in your container, it is sufficient to list them in the ETHERPAD_PLUGINS build variable.
-The variable value has to be a space separated, double quoted list of plugin names (see examples).
-
-Some plugins will need personalized settings. Just refer to the previous section, and include them in your custom `settings.json.docker`.
-
-### Rebuilding including export functionality for DOC/PDF/ODT
-
-If you want to be able to export your pads to DOC/PDF/ODT files, you can install
-either Abiword or Libreoffice via setting a build variable.
-
-#### Via Abiword
-
-For installing Abiword, set the `INSTALL_ABIWORD` build variable to any value.
-
-Also, you will need to configure the path to the abiword executable
-via setting the `abiword` property in `<BASEDIR>/settings.json.docker` to 
-`/usr/bin/abiword` or via setting the environment variable  `ABIWORD` to 
-`/usr/bin/abiword`.
-
-#### Via Libreoffice
-
-For installing Libreoffice instead, set the `INSTALL_SOFFICE` build variable
-to any value.
-
-Also, you will need to configure the path to the libreoffice executable
-via setting the `soffice` property in `<BASEDIR>/settings.json.docker` to 
-`/usr/bin/soffice` or via setting the environment variable  `SOFFICE` to 
-`/usr/bin/soffice`.
-
-### Examples
-
-Build a Docker image from the currently checked-out code:
-```bash
-docker build --tag <YOUR_USERNAME>/etherpad .
-```
-
-Include two plugins in the container:
-```bash
-docker build --build-arg ETHERPAD_PLUGINS="ep_comments_page ep_author_neat" --tag <YOUR_USERNAME>/etherpad .
-```
-
-## Running your instance:
-
-To run your instance:
-```bash
-docker run --detach --publish <DESIRED_PORT>:9001 <YOUR_USERNAME>/etherpad
-```
-
-And point your browser to `http://<YOUR_IP>:<DESIRED_PORT>`
-
-## Options available by default
-
-The `settings.json.docker` available by default allows to control almost every setting via environment variables.
-
-### General
-
-| Variable           | Description                                                                                | Default                                                                                                                                                                                                                             |
-| ------------------ | ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `TITLE`            | The name of the instance                                                                   | `Etherpad`                                                                                                                                                                                                                          |
-| `FAVICON`          | favicon default name, or a fully specified URL to your own favicon                         | `favicon.ico`                                                                                                                                                                                                                       |
-| `DEFAULT_PAD_TEXT` | The default text of a pad                                                                  | `Welcome to Etherpad! This pad text is synchronized as you type, so that everyone viewing this page sees the same text. This allows you to collaborate seamlessly on documents! Get involved with Etherpad at https://etherpad.org` |
-| `IP`               | IP which etherpad should bind at. Change to `::` for IPv6                                  | `0.0.0.0`                                                                                                                                                                                                                           |
-| `PORT`             | port which etherpad should bind at                                                         | `9001`                                                                                                                                                                                                                              |
-| `ADMIN_PASSWORD`   | the password for the `admin` user (leave unspecified if you do not want to create it)      |                                                                                                                                                                                                                                     |
-| `USER_PASSWORD`    | the password for the first user `user` (leave unspecified if you do not want to create it) |                                                                                                                                                                                                                                     |
-
-
-### Database
-
-| Variable      | Description                                                    | Default                                                               |
-| ------------- | -------------------------------------------------------------- | --------------------------------------------------------------------- |
-| `DB_TYPE`     | a database supported by https://www.npmjs.com/package/ueberdb2 | not set, thus will fall back to `DirtyDB` (please choose one instead) |
-| `DB_HOST`     | the host of the database                                       |                                                                       |
-| `DB_PORT`     | the port of the database                                       |                                                                       |
-| `DB_NAME`     | the database name                                              |                                                                       |
-| `DB_USER`     | a database user with sufficient permissions to create tables   |                                                                       |
-| `DB_PASS`     | the password for the database username                         |                                                                       |
-| `DB_CHARSET`  | the character set for the tables (only required for MySQL)     |                                                                       |
-| `DB_FILENAME` | in case `DB_TYPE` is `DirtyDB` or `sqlite`, the database file. | `var/dirty.db`, `var/etherpad.sq3`                                    |
-
-If your database needs additional settings, you will have to use a personalized `settings.json.docker` and rebuild the container (or otherwise put the updated `settings.json` inside your image).
-
-
-### Pad Options
-
-| Variable                         | Description | Default |
-| -------------------------------- | ----------- | ------- |
-| `PAD_OPTIONS_NO_COLORS`          |             | `false` |
-| `PAD_OPTIONS_SHOW_CONTROLS`      |             | `true`  |
-| `PAD_OPTIONS_SHOW_CHAT`          |             | `true`  |
-| `PAD_OPTIONS_SHOW_LINE_NUMBERS`  |             | `true`  |
-| `PAD_OPTIONS_USE_MONOSPACE_FONT` |             | `false` |
-| `PAD_OPTIONS_USER_NAME`          |             | `null`  |
-| `PAD_OPTIONS_USER_COLOR`         |             | `null`  |
-| `PAD_OPTIONS_RTL`                |             | `false` |
-| `PAD_OPTIONS_ALWAYS_SHOW_CHAT`   |             | `false` |
-| `PAD_OPTIONS_CHAT_AND_USERS`     |             | `false` |
-| `PAD_OPTIONS_LANG`               |             | `null`  |
-
-
-### Shortcuts
-
-| Variable                            | Description                                      | Default |
-| ----------------------------------- | ------------------------------------------------ | ------- |
-| `PAD_SHORTCUTS_ENABLED_ALT_F9`      | focus on the File Menu and/or editbar            | `true`  |
-| `PAD_SHORTCUTS_ENABLED_ALT_C`       | focus on the Chat window                         | `true`  |
-| `PAD_SHORTCUTS_ENABLED_CMD_S`       | save a revision                                  | `true`  |
-| `PAD_SHORTCUTS_ENABLED_CMD_Z`       | undo/redo                                        | `true`  |
-| `PAD_SHORTCUTS_ENABLED_CMD_Y`       | redo                                             | `true`  |
-| `PAD_SHORTCUTS_ENABLED_CMD_I`       | italic                                           | `true`  |
-| `PAD_SHORTCUTS_ENABLED_CMD_B`       | bold                                             | `true`  |
-| `PAD_SHORTCUTS_ENABLED_CMD_U`       | underline                                        | `true`  |
-| `PAD_SHORTCUTS_ENABLED_CMD_H`       | backspace                                        | `true`  |
-| `PAD_SHORTCUTS_ENABLED_CMD_5`       | strike through                                   | `true`  |
-| `PAD_SHORTCUTS_ENABLED_CMD_SHIFT_1` | ordered list                                     | `true`  |
-| `PAD_SHORTCUTS_ENABLED_CMD_SHIFT_2` | shows a gritter popup showing a line author      | `true`  |
-| `PAD_SHORTCUTS_ENABLED_CMD_SHIFT_L` | unordered list                                   | `true`  |
-| `PAD_SHORTCUTS_ENABLED_CMD_SHIFT_N` | ordered list                                     | `true`  |
-| `PAD_SHORTCUTS_ENABLED_CMD_SHIFT_C` | clear authorship                                 | `true`  |
-| `PAD_SHORTCUTS_ENABLED_DELETE`      |                                                  | `true`  |
-| `PAD_SHORTCUTS_ENABLED_RETURN`      |                                                  | `true`  |
-| `PAD_SHORTCUTS_ENABLED_ESC`         | in mozilla versions 14-19 avoid reconnecting pad | `true`  |
-| `PAD_SHORTCUTS_ENABLED_TAB`         | indent                                           | `true`  |
-| `PAD_SHORTCUTS_ENABLED_CTRL_HOME`   | scroll to top of pad                             | `true`  |
-| `PAD_SHORTCUTS_ENABLED_PAGE_UP`     |                                                  | `true`  |
-| `PAD_SHORTCUTS_ENABLED_PAGE_DOWN`   |                                                  | `true`  |
-
-
-### Skins
-
-You can use the UI skin variants builder at `/p/test#skinvariantsbuilder`
-
-For the colibris skin only, you can choose how to render the three main containers:
-  * toolbar (top menu with icons)
-  * editor (containing the text of the pad)
-  * background (area outside of editor, mostly visible when using page style)
-
-For each of the 3 containers you can choose 4 color combinations:
-   * super-light
-   * light
-   * dark
-   * super-dark
-
-For the editor container, you can also make it full width by adding `full-width-editor` variant (by default editor is rendered as a page, with a max-width of 900px).
-
-| Variable        | Description                                                                    | Default                                                   |
-| --------------- | ------------------------------------------------------------------------------ | --------------------------------------------------------- |
-| `SKIN_NAME`     | either `no-skin`, `colibris` or an existing directory under `src/static/skins` | `colibris`                                                |
-| `SKIN_VARIANTS` | multiple skin variants separated by spaces                                     | `super-light-toolbar super-light-editor light-background` |
-
-
-### Logging
-
-| Variable             | Description                                          | Default |
-| -------------------- | ---------------------------------------------------- | ------- |
-| `LOGLEVEL`           | valid values are `DEBUG`, `INFO`, `WARN` and `ERROR` | `INFO`  |
-| `DISABLE_IP_LOGGING` | Privacy: disable IP logging                          | `false` |
-
-
-### Advanced
-
-| Variable                          | Description                                                                                                                                                                                            | Default               |
-| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------    |
-| `COOKIE_SAME_SITE`                | Value of the SameSite cookie property.                                                                                                                                                                 | `"Lax"`               |
-| `COOKIE_SESSION_LIFETIME`         | How long (ms) a user can be away before they must log in again.                                                                                                                                        | `864000000` (10 days) |
-| `COOKIE_SESSION_REFRESH_INTERVAL` | How often (ms) to write the latest cookie expiration time.                                                                                                                                             | `86400000` (1 day)    |
-| `SHOW_SETTINGS_IN_ADMIN_PAGE`     | hide/show the settings.json in admin page                                                                                                                                                              | `true`                |
-| `TRUST_PROXY`                     | set to `true` if you are using a reverse proxy in front of Etherpad (for example: Traefik for SSL termination via Let's Encrypt). This will affect security and correctness of the logs if not done    | `false`               |
-| `IMPORT_MAX_FILE_SIZE`            | maximum allowed file size when importing a pad, in bytes.                                                                                                                                              | `52428800` (50 MB)    |
-| `IMPORT_EXPORT_MAX_REQ_PER_IP`    | maximum number of import/export calls per IP.                                                                                                                                                          | `10`                  |
-| `IMPORT_EXPORT_RATE_LIMIT_WINDOW` | the call rate for import/export requests will be estimated in this time window (in milliseconds)                                                                                                       | `90000`               |
-| `COMMIT_RATE_LIMIT_DURATION`      | duration of the rate limit window for commits by individual users/IPs (in seconds)                                                                                                                     | `1`                   |
-| `COMMIT_RATE_LIMIT_POINTS`        | maximum number of changes per IP to allow during the rate limit window                                                                                                                                 | `10`                  |
-| `SUPPRESS_ERRORS_IN_PAD_TEXT`     | Should we suppress errors from being visible in the default Pad Text?                                                                                                                                  | `false`               |
-| `REQUIRE_SESSION`                 | If this option is enabled, a user must have a session to access pads. This effectively allows only group pads to be accessed.                                                                          | `false`               |
-| `EDIT_ONLY`                       | Users may edit pads but not create new ones. Pad creation is only via the API. This applies both to group pads and regular pads.                                                                       | `false`               |
-| `MINIFY`                          | If true, all css & js will be minified before sending to the client. This will improve the loading performance massively, but makes it difficult to debug the javascript/css                           | `true`                |
-| `MAX_AGE`                         | How long may clients use served javascript code (in seconds)? Not setting this may cause problems during deployment. Set to 0 to disable caching.                                                      | `21600` (6 hours)     |
-| `ABIWORD`                         | Absolute path to the Abiword executable. Abiword is needed to get advanced import/export features of pads. Setting it to null disables Abiword and will only allow plain text and HTML import/exports. | `null`                |
-| `SOFFICE`                         | This is the absolute path to the soffice executable. LibreOffice can be used in lieu of Abiword to export pads. Setting it to null disables LibreOffice exporting.                                     | `null`                |
-| `TIDY_HTML`                       | Path to the Tidy executable. Tidy is used to improve the quality of exported pads. Setting it to null disables Tidy.                                                                                   | `null`                |
-| `ALLOW_UNKNOWN_FILE_ENDS`         | Allow import of file types other than the supported ones: txt, doc, docx, rtf, odt, html & htm                                                                                                         | `true`                |
-| `REQUIRE_AUTHENTICATION`          | This setting is used if you require authentication of all users. Note: "/admin" always requires authentication.                                                                                        | `false`               |
-| `REQUIRE_AUTHORIZATION`           | Require authorization by a module, or a user with is_admin set, see below.                                                                                                                             | `false`               |
-| `AUTOMATIC_RECONNECTION_TIMEOUT`  | Time (in seconds) to automatically reconnect pad when a "Force reconnect" message is shown to user. Set to 0 to disable automatic reconnection.                                                        | `0`                   |
-| `FOCUS_LINE_PERCENTAGE_ABOVE`     | Percentage of viewport height to be additionally scrolled. e.g. 0.5, to place caret line in the middle of viewport, when user edits a line above of the viewport. Set to 0 to disable extra scrolling  | `0`                   |
-| `FOCUS_LINE_PERCENTAGE_BELOW`     | Percentage of viewport height to be additionally scrolled. e.g. 0.5, to place caret line in the middle of viewport, when user edits a line below of the viewport. Set to 0 to disable extra scrolling  | `0`                   |
-| `FOCUS_LINE_PERCENTAGE_ARROW_UP`  | Percentage of viewport height to be additionally scrolled when user presses arrow up in the line of the top of the viewport. Set to 0 to let the scroll to be handled as default by Etherpad           | `0`                   |
-| `FOCUS_LINE_DURATION`             | Time (in milliseconds) used to animate the scroll transition. Set to 0 to disable animation                                                                                                            | `0`                   |
-| `FOCUS_LINE_CARET_SCROLL`         | Flag to control if it should scroll when user places the caret in the last line of the viewport                                                                                                        | `false`               |
-| `SOCKETIO_MAX_HTTP_BUFFER_SIZE`   | The maximum size (in bytes) of a single message accepted via Socket.IO. If a client sends a larger message, its connection gets closed to prevent DoS (memory exhaustion) attacks.                     | `10000`               |
-| `LOAD_TEST`                       | Allow Load Testing tools to hit the Etherpad Instance. WARNING: this will disable security on the instance.                                                                                            | `false`               |
-| `DUMP_ON_UNCLEAN_EXIT`            | Enable dumping objects preventing a clean exit of Node.js. WARNING: this has a significant performance impact.                                                                                         | `false`               |
-| `EXPOSE_VERSION`                  | Expose Etherpad version in the web interface and in the Server http header. Do not enable on production machines.                                                                                      | `false`               |
-
-
-### Examples
-
-Use a Postgres database, no admin user enabled:
-
-```shell
-docker run -d \
-	--name etherpad         \
-	-p 9001:9001            \
-	-e 'DB_TYPE=postgres'   \
-	-e 'DB_HOST=db.local'   \
-	-e 'DB_PORT=4321'       \
-	-e 'DB_NAME=etherpad'   \
-	-e 'DB_USER=dbusername' \
-	-e 'DB_PASS=mypassword' \
-	etherpad/etherpad
-```
-
-Run enabling the administrative user `admin`:
-
-```shell
-docker run -d \
-	--name etherpad \
-	-p 9001:9001 \
-	-e 'ADMIN_PASSWORD=supersecret' \
-	etherpad/etherpad
-```
-
-Run a test instance running DirtyDB on a persistent volume:
-
-```
-docker run -d \
-	-v etherpad_data:/opt/etherpad-lite/var \
-	-p 9001:9001 \
-	etherpad/etherpad
-```

doc/documentation.adoc

@@ -1,6 +1,4 @@
-# About this Documentation
-
-<!-- type=misc -->
+== About this Documentation
 
 The goal of this documentation is to comprehensively explain Etherpad,
 both from a reference as well as a conceptual point of view.

doc/index.adoc

@@ -0,0 +1,25 @@
+:version: {VERSION}
+
+= Etherpad v{version} Manual & Documentation
+:stylesheet: assets/style.css
+:toc:
+:toclevels: 4
+:source-highlighter: highlight.js
+
+include::./documentation.adoc[]
+
+include::./stats.adoc[]
+
+include::./localization.adoc[]
+
+include::./docker.adoc[]
+
+include::./skins.adoc[]
+
+include::./api/api.adoc[]
+
+include::./plugins.adoc[]
+
+include::./cookies.adoc[]
+
+include::./database.adoc[]

doc/index.md

@@ -1,9 +0,0 @@
-@include documentation
-@include stats
-@include localization
-@include docker
-@include skins
-@include api/api
-@include plugins
-@include cookies
-@include database

doc/localization.adoc

@@ -1,105 +1,121 @@
-# Localization
+== Localization
 Etherpad provides a multi-language user interface, that's apart from your users' content, so users from different countries can collaborate on a single document, while still having the user interface displayed in their mother tongue.
 
 
-## Translating
+=== Translating
 We rely on https://translatewiki.net to handle the translation process for us, so if you'd like to help...
 
 1. Sign up at https://translatewiki.net
-2. Visit our [TWN project page](https://translatewiki.net/wiki/Translating:Etherpad_lite)
+2. Visit our https://translatewiki.net/wiki/Translating:Etherpad_lite[TWN project page]
 3. Click on `Translate Etherpad lite interface`
 4. Choose a target language, you'd like to translate our interface to, and hit `Fetch`
 5. Start translating!
 
 Translations will be send back to us regularly and will eventually appear in the next release.
 
-## Implementation
+=== Implementation
 
-### Server-side
+==== Server-side
 `/src/locales` contains files for all supported languages which contain the translated strings. Translation files are simple `*.json` files and look like this:
 
-```json
+[source,json]
+----
 { "pad.modals.connected": "Connecté."
 , "pad.modals.uderdup": "Ouvrir dans une nouvelle fenêtre."
 , "pad.toolbar.unindent.title": "Dèsindenter"
 , "pad.toolbar.undo.title": "Annuler (Ctrl-Z)"
-, "timeslider.pageTitle": "{{appTitle}} Curseur temporel"
+, "timeslider.pageTitle": "{{appTitle}} Curseur temporel",
 , ...
 }
-```
+----
 
 Each translation consists of a key (the id of the string that is to be translated) and the translated string. Terms in curly braces must not be touched but left as they are, since they represent a dynamically changing part of the string like a variable. Imagine a message welcoming a user: `Welcome, {{userName}}!` would be translated as `Ahoy, {{userName}}!` in pirate.
 
-### Client-side
-We use a `language` cookie to save your language settings if you change them. If you don't, we autodetect your locale using information from your browser. Then, the preferred language is fed into a library called [html10n.js](https://github.com/marcelklehr/html10n.js), which loads the appropriate translations and applies them to our templates. Its features include translation params, pluralization, include rules and a nice javascript API.
+==== Client-side
+We use a `language` cookie to save your language settings if you change them. If you don't, we autodetect your locale using information from your browser. Then, the preferred language is fed into a library called https://github.com/marcelklehr/html10n.js[html10n.js], which loads the appropriate translations and applies them to our templates. Its features include translation params, pluralization, include rules and a nice javascript API.
 
 
 
-## Localizing plugins
+=== Localizing plugins
 
-### 1. Mark the strings to translate
+==== 1. Mark the strings to translate
 
 In the template files of your plugin, change all hardcoded messages/strings...
 
 from:
-```html
+
+[source,html]
+----
 <option value="0">Heading 1</option>
-```
+----
 to:
-```html
+
+[source,html]
+----
 <option data-l10n-id="ep_heading.h1" value="0"></option>
-```
+----
 
 In the javascript files of your plugin, change all hardcoded messages/strings...
 
 from:
-```js
-alert ('Chat');
-```
-to:
-```js
-alert(window._('pad.chat'));
-```
-### 2. Create translate files in the locales directory of your plugin
 
-* The name of the file must be the language code of the language it contains translations for (see [supported lang codes](https://joker-x.github.com/languages4translatewiki/test/); e.g. en ? English, es ? Spanish...)
+[source,js]
+----
+alert ('Chat');
+----
+to:
+
+[source,js]
+----
+alert(window._('pad.chat'));
+----
+==== 2. Create translate files in the locales directory of your plugin
+
+* The name of the file must be the language code of the language it contains translations for (see https://joker-x.github.com/languages4translatewiki/test/[supported lang codes]; e.g. en ? English, es ? Spanish...)
 * The extension of the file must be `.json`
 * The default language is English, so your plugin should always provide `en.json`
 * In order to avoid naming conflicts, your message keys should start with the name of your plugin followed by a dot (see below)
 
 *ep_your-plugin/locales/en.json*
-```
+
+[source, json]
+----
 { "ep_your-plugin.h1": "Heading 1"
 }
-```
+----
 
 *ep_your-plugin/locales/es.json*
-```
+
+[source, json]
+----
 { "ep_your-plugin.h1": "Título 1"
 }
-```
+----
 
 Every time the http server is started, it will auto-detect your messages and merge them automatically with the core messages.
 
-### Overwrite core messages
+==== Overwrite core messages
 
 You can overwrite Etherpad's core messages in your plugin's locale files.
 For example, if you want to replace `Chat` with `Notes`, simply add...
 
 *ep_your-plugin/locales/en.json*
-```
+
+[source,json]
+----
 { "ep_your-plugin.h1": "Heading 1"
 , "pad.chat": "Notes"
 }
-```
+----
 
-## Customization for Administrators
+=== Customization for Administrators
 
 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`:
 
-```
+[source,json]
+----
   "customLocaleStrings": {
     "fr": {
       "index.newPad": "Créer un document"
@@ -111,4 +127,4 @@ For example, let's say you want to change the text on the "New Pad" button on Et
       "index.newPad": "Create a document"
     }
   }
-```
+----

doc/plugins.adoc

@@ -1,4 +1,4 @@
-# Plugins
+== Plugins
 
 Etherpad allows you to extend its functionality with plugins. A plugin registers
 hooks (functions) for certain events (thus certain features) in Etherpad to
@@ -14,11 +14,12 @@ You can also browse to `http://yourEtherpadInstan.ce/admin/plugins`, which will
 list all installed plugins and those available on npm. It even provides
 functionality to search through all available plugins.
 
-## Folder structure
+=== Folder structure
 
 Ideally a plugin has the following folder structure:
 
-```
+[source]
+----
 ep_<plugin>/
  ├ .github/
  │  └ workflows/
@@ -44,7 +45,7 @@ ep_<plugin>/
  ├ index.js              ◄─ server-side code
  ├ package.json
  └ package-lock.json
-```
+----
 
 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
@@ -58,14 +59,15 @@ 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.)
 
-## Plugin definition
+=== Plugin definition
 
 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
 [hooks](#all_hooks).)
 
-```json
+[source,json]
+----
 {
   "parts": [
     {
@@ -80,7 +82,7 @@ documentation of all available events to hook into can be found in chapter
     }
   ]
 }
-```
+----
 
 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
@@ -119,7 +121,7 @@ function in `index.js` from the `ep_example` plugin:
 * `"authorize": ":"`
 * `"authorize": ""`
 
-### Client hooks and server hooks
+==== Client hooks and server hooks
 
 There are server hooks, which will be executed on the server (e.g.
 `expressCreateServer`), and there are client hooks, which are executed on the
@@ -128,7 +130,7 @@ environment your code is running in, e.g. don't try to access `process`, if you
 know your code will be run on the client, and likewise, don't try to access
 `window` on the server...
 
-### Styling
+==== Styling
 
 When you install a client-side plugin (e.g. one that implements at least one
 client-side hook), the plugin name is added to the `class` attribute of the div
@@ -137,35 +139,38 @@ tuning the appearance of the main UI in your plugin.
 
 For example, this is the markup with no plugins installed:
 
-```html
+[source,html]
+----
 <div id="editorcontainerbox" class="">
-```
+----
 
 and this is the contents after installing `someplugin`:
 
-```html
+[source,html]
+----
 <div id="editorcontainerbox" class="ep_someplugin">
-```
+----
 
 This feature was introduced in Etherpad **1.8**.
 
-### Parts
+==== Parts
 
 As your plugins become more and more complex, you will find yourself in the need
 to manage dependencies between plugins. E.g. you want the hooks of a certain
 plugin to be executed before (or after) yours. You can also manage these
 dependencies in your plugin definition file `ep.json`:
 
-```json
+[source,json]
+----
 {
   "parts": [
     {
       "name": "onepart",
       "pre": [],
-      "post": ["ep_onemoreplugin/partone"]
+      "post": ["ep_onemoreplugin/partone"],
       "hooks": {
         "storeBar": "ep_monospace/plugin:storeBar",
-        "getFoo": "ep_monospace/plugin:getFoo",
+        "getFoo": "ep_monospace/plugin:getFoo"
       }
     },
     {
@@ -179,14 +184,14 @@ dependencies in your plugin definition file `ep.json`:
     }
   ]
 }
-```
+----
 
 Usually a plugin will add only one functionality at a time, so it will probably
 only use one `part` definition to register its hooks. However, sometimes you
 have to put different (unrelated) functionalities into one plugin. For this you
 will want use parts, so other plugins can depend on them.
 
-#### pre/post
+===== pre/post
 
 The `"pre"` and `"post"` definitions, affect the order in which parts of a
 plugin are executed. This ensures that plugins and their hooks are executed in
@@ -207,17 +212,18 @@ environment, `"post"` could definitely be useful.
 Also, note that dependencies should *also* be listed in your package.json, so
 they can be `npm install`'d automagically when your plugin gets installed.
 
-## Package definition
+=== Package definition
 
-Your plugin must also contain a [package definition
-file](https://docs.npmjs.com/files/package.json), called package.json, in the
+Your plugin must also contain a https://docs.npmjs.com/files/package.json[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.
 
-```json
+[source,json]
+----
 {
   "name": "ep_PLUGINNAME",
   "version": "0.0.1",
@@ -227,9 +233,9 @@ publish your plugin.
   "dependencies": {"MODULE": "0.3.20"},
   "engines": {"node": ">=12.17.0"}
 }
-```
+----
 
-## Templates
+=== Templates
 
 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
@@ -237,7 +243,7 @@ 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>.
 
-## Writing and running front-end tests for your plugin
+=== Writing and running front-end tests for your plugin
 
 Etherpad allows you to easily create front-end tests for plugins.
 

doc/skins.adoc

@@ -1,4 +1,4 @@
-# Skins
+== Skins
 You can customize Etherpad appearance using skins.
 A skin is a directory located under `static/skins/<skin_name>`, with the following contents:
 

doc/stats.adoc

@@ -1,4 +1,5 @@
-# Statistics
+== Statistics
+
 Etherpad keeps track of the goings-on inside the edit machinery. If you'd like to have a look at this, just point your browser to `/stats`.
 
 We currently measure:
@@ -13,6 +14,6 @@ We currently measure:
  - http500 (meter)
  - memoryUsage (gauge)
 
-Under the hood, we are happy to rely on [measured](https://github.com/felixge/node-measured) for all our metrics needs.
+Under the hood, we are happy to rely on https://github.com/felixge/node-measured[measured] for all our metrics needs.
 
-To modify or simply access our stats in your plugin, simply `require('ep_etherpad-lite/stats')` which is a [`measured.Collection`](https://yaorg.github.io/node-measured/packages/measured-core/Collection.html).
+To modify or simply access our stats in your plugin, simply `require('ep_etherpad-lite/stats')` which is a https://yaorg.github.io/node-measured/packages/measured-core/Collection.html[`measured.Collection`].

doc/template.html

@@ -1,23 +0,0 @@
-<!doctype html>
-<html lang="en">
-<head>
-  <meta charset="utf-8">
-  <title>__SECTION__ - Etherpad v__VERSION__ Manual &amp; Documentation</title>
-  <link rel="stylesheet" href="assets/style.css">
-</head>
-<body class="apidoc" id="api-section-__FILENAME__">
-  <header id="header">
-    <h1>Etherpad v__VERSION__ Manual &amp; Documentation</h1>
-  </header>
-
-  <div id="toc">
-    <h2>Table of Contents</h2>
-    __TOC__
-  </div>
-
-  <div id="apicontent">
-    __CONTENT__
-  </div>
-
-</body>
-</html>

make_docs.js

@@ -0,0 +1,58 @@
+const { exec } = require('child_process');
+const fs = require('fs')
+const path = require('path')
+
+
+const pjson = require('./src/package.json')
+const VERSION=pjson.version
+console.log(`Building docs for version ${VERSION}`)
+
+const createDirIfNotExists = (dir) => {
+    if (!fs.existsSync(dir)){
+        fs.mkdirSync(dir)
+    }
+}
+
+
+function copyFolderSync(from, to) {
+   if(fs.existsSync(to)){
+       const stat = fs.lstatSync(to)
+       if (stat.isDirectory()){
+           fs.rmSync(to, { recursive: true })
+       }
+       else{
+           fs.rmSync(to)
+       }
+   }
+    fs.mkdirSync(to);
+    fs.readdirSync(from).forEach(element => {
+        if (fs.lstatSync(path.join(from, element)).isFile()) {
+            fs.copyFileSync(path.join(from, element), path.join(to, element))
+        } else {
+            copyFolderSync(path.join(from, element), path.join(to, element))
+        }
+    });
+}
+
+exec('asciidoctor -v', (err,stdout)=>{
+    if (err){
+        console.log('Please install asciidoctor')
+        console.log('https://asciidoctor.org/docs/install-toolchain/')
+        process.exit(1)
+    }
+});
+
+
+createDirIfNotExists('./out')
+createDirIfNotExists('./out/doc')
+createDirIfNotExists('./out/doc/api')
+
+
+
+exec(`asciidoctor -D out/doc doc/index.adoc */**.adoc -a VERSION=${VERSION}`)
+exec(`asciidoctor -D out/doc/api  ./doc/api/*.adoc -a VERSION=${VERSION}`)
+
+copyFolderSync('./doc/easysync', './out/doc/easysync')
+copyFolderSync('./doc/assets', './out/doc/assets')
+copyFolderSync('./doc/easysync', './out/doc/easysync')
+copyFolderSync('./doc/images', './out/doc/images')

src/bin/release.js

@@ -9,6 +9,7 @@ const childProcess = require('child_process');
 const log4js = require('log4js');
 const path = require('path');
 const semver = require('semver');
+const {exec} = require("child_process");
 
 log4js.replaceConsole();
 
@@ -76,6 +77,15 @@ const assertUpstreamOk = (branch, opts = {}) => {
   }
 };
 
+// Check if asciidoctor is installed
+exec('asciidoctor -v', (err,stdout)=>{
+  if (err){
+    console.log('Please install asciidoctor')
+    console.log('https://asciidoctor.org/docs/install-toolchain/')
+    process.exit(1)
+  }
+});
+
 const dirExists = (dir) => {
   try {
     return fs.statSync(dir).isDirectory();
@@ -168,7 +178,7 @@ try {
 
 try {
   console.log('Building documentation...');
-  run('make docs');
+  run('node ./make_docs.js');
   console.log('Updating ether.github.com master branch...');
   run('git pull --ff-only', {cwd: '../ether.github.com/'});
   console.log('Committing documentation...');