diff --git a/.github/dependabot.yml b/.github/dependabot.yml
index 263f5a783..1e7ac79ed 100644
--- a/.github/dependabot.yml
+++ b/.github/dependabot.yml
@@ -10,7 +10,11 @@ updates:
schedule:
interval: "daily"
- package-ecosystem: "npm"
- directory: "/src"
+ directory: "/"
schedule:
interval: "daily"
versioning-strategy: "increase"
+ open-pull-requests-limit: 30
+ groups:
+ dev-dependencies:
+ dependency-type: "development"
\ No newline at end of file
diff --git a/.github/workflows/backend-tests.yml b/.github/workflows/backend-tests.yml
index 0dd1000d8..e8fe12ae1 100644
--- a/.github/workflows/backend-tests.yml
+++ b/.github/workflows/backend-tests.yml
@@ -1,7 +1,13 @@
name: "Backend tests"
# any branch is useful for testing before a PR is submitted
-on: [push, pull_request]
+on:
+ push:
+ paths-ignore:
+ - "doc/**"
+ pull_request:
+ paths-ignore:
+ - "doc/**"
permissions:
contents: read
diff --git a/.github/workflows/build-and-deploy-docs.yml b/.github/workflows/build-and-deploy-docs.yml
new file mode 100644
index 000000000..107736faf
--- /dev/null
+++ b/.github/workflows/build-and-deploy-docs.yml
@@ -0,0 +1,70 @@
+# Workflow for deploying static content to GitHub Pages
+name: Deploy Docs to GitHub Pages
+
+on:
+ # Runs on pushes targeting the default branch
+ push:
+ branches: ["develop"]
+ paths:
+ - doc/** # Only run workflow when changes are made to the doc directory
+ # Allows you to run this workflow manually from the Actions tab
+ workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+ contents: read
+ pages: write
+ id-token: write
+ packages: read
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+ group: "pages"
+ cancel-in-progress: false
+
+jobs:
+ # Single deploy job since we're just deploying
+ deploy:
+ environment:
+ name: github-pages
+ url: ${{ steps.deployment.outputs.page_url }}
+ runs-on: ubuntu-latest
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v4
+ - name: Setup Pages
+ uses: actions/configure-pages@v5
+ - uses: pnpm/action-setup@v3
+ name: Install pnpm
+ with:
+ version: 8
+ run_install: false
+ - name: Get pnpm store directory
+ shell: bash
+ run: |
+ echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV
+ - uses: actions/cache@v4
+ name: Setup pnpm cache
+ with:
+ path: ${{ env.STORE_PATH }}
+ key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
+ restore-keys: |
+ ${{ runner.os }}-pnpm-store-
+ - name: Only install direct dependencies
+ run: pnpm config set auto-install-peers false
+ - name: Install dependencies
+ run: pnpm install
+ - name: Build app
+ working-directory: doc
+ run: pnpm run docs:build
+ env:
+ COMMIT_REF: ${{ github.sha }}
+ - name: Upload artifact
+ uses: actions/upload-pages-artifact@v3
+ with:
+ # Upload entire repository
+ path: './doc/.vitepress/dist'
+ - name: Deploy to GitHub Pages
+ id: deployment
+ uses: actions/deploy-pages@v4
diff --git a/.github/workflows/codeql-analysis.yml b/.github/workflows/codeql-analysis.yml
index eaf004e54..94dd1ac75 100644
--- a/.github/workflows/codeql-analysis.yml
+++ b/.github/workflows/codeql-analysis.yml
@@ -6,6 +6,8 @@ on:
pull_request:
# The branches below must be a subset of the branches above
branches: [develop]
+ paths-ignore:
+ - 'doc/**'
schedule:
- cron: '0 13 * * 1'
diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml
index 7e728ec64..c01bcc065 100644
--- a/.github/workflows/docker.yml
+++ b/.github/workflows/docker.yml
@@ -1,9 +1,13 @@
name: Docker
on:
pull_request:
+ paths-ignore:
+ - 'doc/**'
push:
branches:
- 'develop'
+ paths-ignore:
+ - 'doc/**'
tags:
- 'v?[0-9]+.[0-9]+.[0-9]+'
env:
diff --git a/.github/workflows/frontend-admin-tests.yml b/.github/workflows/frontend-admin-tests.yml
index cb89d2b91..cb9d74242 100644
--- a/.github/workflows/frontend-admin-tests.yml
+++ b/.github/workflows/frontend-admin-tests.yml
@@ -1,7 +1,10 @@
# Leave the powered by Sauce Labs bit in as this means we get additional concurrency
name: "Frontend admin tests powered by Sauce Labs"
-on: [push]
+on:
+ push:
+ paths-ignore:
+ - 'doc/**'
permissions:
contents: read # to fetch code (actions/checkout)
diff --git a/.github/workflows/frontend-tests.yml b/.github/workflows/frontend-tests.yml
index 93018ea0a..6966f6dc4 100644
--- a/.github/workflows/frontend-tests.yml
+++ b/.github/workflows/frontend-tests.yml
@@ -1,7 +1,10 @@
# Leave the powered by Sauce Labs bit in as this means we get additional concurrency
name: "Frontend tests powered by Sauce Labs"
-on: [push]
+on:
+ push:
+ paths-ignore:
+ - 'doc/**'
permissions:
contents: read # to fetch code (actions/checkout)
diff --git a/.github/workflows/lint-package-lock.yml b/.github/workflows/lint-package-lock.yml
deleted file mode 100644
index f1073172a..000000000
--- a/.github/workflows/lint-package-lock.yml
+++ /dev/null
@@ -1,34 +0,0 @@
-name: "Lint"
-
-# any branch is useful for testing before a PR is submitted
-on: [push, pull_request]
-
-permissions:
- contents: read
-
-jobs:
- lint-package-lock:
- # run on pushes to any branch
- # run on PRs from external forks
- if: |
- (github.event_name != 'pull_request')
- || (github.event.pull_request.head.repo.id != github.event.pull_request.base.repo.id)
- name: package-lock.json
- runs-on: ubuntu-latest
- steps:
- -
- name: Checkout repository
- uses: actions/checkout@v4
- -
- uses: actions/setup-node@v4
- with:
- node-version: 20
- -
- name: Run lockfile-lint on package-lock.json
- run: >
- npx lockfile-lint
- --path src/package-lock.json
- --allowed-hosts npm
- --allowed-schemes https:
- --allowed-schemes github:
- --allowed-urls github:mapbox/node-sqlite3#593c9d498be2510d286349134537e3bf89401c4a
diff --git a/.github/workflows/load-test.yml b/.github/workflows/load-test.yml
index d4f1a9b44..c5eab5889 100644
--- a/.github/workflows/load-test.yml
+++ b/.github/workflows/load-test.yml
@@ -1,7 +1,13 @@
name: "Loadtest"
# any branch is useful for testing before a PR is submitted
-on: [push, pull_request]
+on:
+ push:
+ paths-ignore:
+ - "doc/**"
+ pull_request:
+ paths-ignore:
+ - "doc/**"
permissions:
contents: read
diff --git a/.github/workflows/perform-type-check.yml b/.github/workflows/perform-type-check.yml
index 81be2567d..5f47f7076 100644
--- a/.github/workflows/perform-type-check.yml
+++ b/.github/workflows/perform-type-check.yml
@@ -1,7 +1,13 @@
name: "Perform type checks"
# any branch is useful for testing before a PR is submitted
-on: [push, pull_request]
+on:
+ push:
+ paths-ignore:
+ - "doc/**"
+ pull_request:
+ paths-ignore:
+ - "doc/**"
permissions:
contents: read
diff --git a/.github/workflows/rate-limit.yml b/.github/workflows/rate-limit.yml
index dab99fff3..5cf8a7756 100644
--- a/.github/workflows/rate-limit.yml
+++ b/.github/workflows/rate-limit.yml
@@ -1,7 +1,13 @@
name: "rate limit"
# any branch is useful for testing before a PR is submitted
-on: [push, pull_request]
+on:
+ push:
+ paths-ignore:
+ - "doc/**"
+ pull_request:
+ paths-ignore:
+ - "doc/**"
permissions:
contents: read
diff --git a/.github/workflows/upgrade-from-latest-release.yml b/.github/workflows/upgrade-from-latest-release.yml
index 627c85af8..5bc6efd1c 100644
--- a/.github/workflows/upgrade-from-latest-release.yml
+++ b/.github/workflows/upgrade-from-latest-release.yml
@@ -1,7 +1,13 @@
name: "Upgrade from latest release"
# any branch is useful for testing before a PR is submitted
-on: [push, pull_request]
+on:
+ push:
+ paths-ignore:
+ - "doc/**"
+ pull_request:
+ paths-ignore:
+ - "doc/**"
permissions:
contents: read
diff --git a/.github/workflows/windows.yml b/.github/workflows/windows.yml
index 99a779234..37b8824f9 100644
--- a/.github/workflows/windows.yml
+++ b/.github/workflows/windows.yml
@@ -1,7 +1,13 @@
name: "Windows Build"
# any branch is useful for testing before a PR is submitted
-on: [push, pull_request]
+on:
+ push:
+ paths-ignore:
+ - "doc/**"
+ pull_request:
+ paths-ignore:
+ - "doc/**"
permissions:
contents: read
diff --git a/.gitignore b/.gitignore
index f577330c9..71584e76b 100644
--- a/.gitignore
+++ b/.gitignore
@@ -27,3 +27,4 @@ plugin_packages
/src/test-results
playwright-report
state.json
+/src/static/oidc
diff --git a/CHANGELOG.md b/CHANGELOG.md
index b565eed2c..5e29702c5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,3 +1,15 @@
+# 2.0.2
+
+### Notable enhancements and fixes
+
+- Fixed the locale loading in the admin panel
+- Added OAuth2.0 support for the Etherpad API. You can now log in into the Etherpad API with your admin user using OAuth2
+
+### Compatibility changes
+
+- The tests now require generating a token from the OAuth secret. You can find the `generateJWTToken` in the common.ts script for plugin endpoint updates.
+
+
# 2.0.1
### Notable enhancements and fixes
diff --git a/Dockerfile b/Dockerfile
index 5bfeca4f7..00b3f4b67 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -7,8 +7,9 @@
FROM node:alpine as adminBuild
WORKDIR /opt/etherpad-lite
-COPY ./admin ./admin
+COPY ./ ./
RUN cd ./admin && npm install -g pnpm && pnpm install && pnpm run build --outDir ./dist
+RUN cd ./ui && pnpm install && pnpm run build --outDir ./dist
FROM node:alpine as build
@@ -40,6 +41,14 @@ ARG SETTINGS=./settings.json.docker
# ETHERPAD_PLUGINS="ep_codepad ep_author_neat"
ARG ETHERPAD_PLUGINS=
+# local plugins to install while building the container. By default no plugins are
+# installed.
+# If given a value, it has to be a space-separated, quoted list of plugin names.
+#
+# EXAMPLE:
+# ETHERPAD_LOCAL_PLUGINS="../ep_my_plugin ../ep_another_plugin"
+ARG ETHERPAD_LOCAL_PLUGINS=
+
# Control whether abiword will be installed, enabling exports to DOC/PDF/ODT formats.
# By default, it is not installed.
# If given any value, abiword will be installed.
@@ -57,7 +66,7 @@ ARG INSTALL_ABIWORD=
ARG INSTALL_SOFFICE=
# Install dependencies required for modifying access.
-RUN apk add shadow bash
+RUN apk add --no-cache shadow bash
# Follow the principle of least privilege: run as unprivileged user.
#
# Running as non-root enables running this image in platforms like OpenShift
@@ -84,7 +93,7 @@ RUN \
mkdir -p /usr/share/man/man1 && \
npm install pnpm -g && \
apk update && apk upgrade && \
- apk add \
+ apk add --no-cache \
ca-certificates \
curl \
git \
@@ -105,11 +114,15 @@ COPY --chown=etherpad:etherpad ./pnpm-workspace.yaml ./package.json ./
FROM build as development
-COPY --chown=etherpad:etherpad ./src/package.json .npmrc ./src/pnpm-lock.yaml ./src/
+COPY --chown=etherpad:etherpad ./src/package.json .npmrc ./src/
COPY --chown=etherpad:etherpad --from=adminBuild /opt/etherpad-lite/admin/dist ./src/templates/admin
+COPY --chown=etherpad:etherpad --from=adminBuild /opt/etherpad-lite/ui/dist ./src/static/oidc
RUN bin/installDeps.sh && \
- { [ -z "${ETHERPAD_PLUGINS}" ] || pnpm run install-plugins ${ETHERPAD_PLUGINS}; }
+ if [ ! -z "${ETHERPAD_PLUGINS}" ] || [ ! -z "${ETHERPAD_LOCAL_PLUGINS}" ]; then \
+ pnpm run install-plugins ${ETHERPAD_PLUGINS} ${ETHERPAD_LOCAL_PLUGINS:+--path ${ETHERPAD_LOCAL_PLUGINS}}; \
+ fi
+
FROM build as production
@@ -118,9 +131,12 @@ ENV ETHERPAD_PRODUCTION=true
COPY --chown=etherpad:etherpad ./src ./src
COPY --chown=etherpad:etherpad --from=adminBuild /opt/etherpad-lite/admin/dist ./src/templates/admin
+COPY --chown=etherpad:etherpad --from=adminBuild /opt/etherpad-lite/ui/dist ./src/static/oidc
-RUN bin/installDeps.sh && rm -rf ~/.npm && \
- { [ -z "${ETHERPAD_PLUGINS}" ] || pnpm run install-plugins ${ETHERPAD_PLUGINS}; }
+RUN bin/installDeps.sh && rm -rf ~/.npm && rm -rf ~/.local && rm -rf ~/.cache && \
+ if [ ! -z "${ETHERPAD_PLUGINS}" ] || [ ! -z "${ETHERPAD_LOCAL_PLUGINS}" ]; then \
+ pnpm run install-plugins ${ETHERPAD_PLUGINS} ${ETHERPAD_LOCAL_PLUGINS:+--path ${ETHERPAD_LOCAL_PLUGINS}}; \
+ fi
# Copy the configuration file.
diff --git a/README.md b/README.md
index b31d1f1a2..b5da2534a 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
# Etherpad: A real-time collaborative editor for the web
-
+
## About
@@ -21,7 +21,6 @@ We're looking for maintainers and have some funding available. Please contact J
### Code Quality
[](https://github.com/ether/etherpad-lite/actions/workflows/codeql-analysis.yml)
-[](https://github.com/ether/etherpad-lite/actions/workflows/lint-package-lock.yml)
### Testing
@@ -121,9 +120,9 @@ Find [here](doc/docker.adoc) information on running Etherpad in a container.
Etherpad is very customizable through plugins.
-
+
-
+
### Available Plugins
@@ -211,7 +210,7 @@ edit `settings.json` and restart Etherpad each time.
Open http://127.0.0.1:9001/p/test#skinvariantsbuilder in your browser and start
playing!
-
+
## Helpful resources
diff --git a/admin/package.json b/admin/package.json
index 9f829a531..4554d9c8c 100644
--- a/admin/package.json
+++ b/admin/package.json
@@ -1,7 +1,7 @@
{
"name": "admin",
"private": true,
- "version": "2.0.1",
+ "version": "2.0.2",
"type": "module",
"scripts": {
"dev": "vite",
@@ -14,26 +14,26 @@
"@radix-ui/react-dialog": "^1.0.5",
"@radix-ui/react-toast": "^1.1.5",
"i18next": "^23.10.1",
- "i18next-browser-languagedetector": "^7.2.0",
- "lucide-react": "^0.356.0",
+ "i18next-browser-languagedetector": "^7.2.1",
+ "lucide-react": "^0.365.0",
"react": "^18.2.0",
"react-dom": "^18.2.0",
- "react-hook-form": "^7.51.0",
+ "react-hook-form": "^7.51.2",
"react-i18next": "^14.1.0",
"react-router-dom": "^6.22.3",
"zustand": "^4.5.2",
- "@types/react": "^18.2.56",
- "@types/react-dom": "^18.2.19",
- "@typescript-eslint/eslint-plugin": "^7.0.2",
- "@typescript-eslint/parser": "^7.0.2",
+ "@types/react": "^18.2.74",
+ "@types/react-dom": "^18.2.24",
+ "@typescript-eslint/eslint-plugin": "^7.5.0",
+ "@typescript-eslint/parser": "^7.5.0",
"@vitejs/plugin-react-swc": "^3.5.0",
- "eslint": "^8.56.0",
+ "eslint": "^9.0.0",
"eslint-plugin-react-hooks": "^4.6.0",
"eslint-plugin-react-refresh": "^0.4.5",
- "socket.io-client": "^4.7.4",
- "typescript": "^5.2.2",
- "vite": "^5.1.4",
- "vite-plugin-static-copy": "^1.0.1",
+ "socket.io-client": "^4.7.5",
+ "typescript": "^5.4.4",
+ "vite": "^5.2.8",
+ "vite-plugin-static-copy": "^1.0.2",
"vite-plugin-svgr": "^4.2.0"
}
}
diff --git a/admin/src/pages/LoginScreen.tsx b/admin/src/pages/LoginScreen.tsx
index ade83cd4c..61ac8993e 100644
--- a/admin/src/pages/LoginScreen.tsx
+++ b/admin/src/pages/LoginScreen.tsx
@@ -46,7 +46,7 @@ export const LoginScreen = ()=>{
-
Passwort
+
Password
{
const plugins:PackageData[] = []
const installedPlugins = {plugins: plugins};
@@ -36,15 +37,20 @@ const persistInstalledPlugins = async () => {
};
async function run() {
- for (const plugin of plugins) {
- if(installFromPath) {
- console.log(`Installing plugin from path: ${plugin}`);
- await linkInstaller.installFromPath(plugin);
+ for (const plugin of registryPlugins) {
+ console.log(`Installing plugin from registry: ${plugin}`)
+ if (plugin.includes('@')) {
+ const [name, version] = plugin.split('@');
+ await linkInstaller.installPlugin(name, version);
continue;
}
- console.log(`Installing plugin from registry: ${plugin}`)
await linkInstaller.installPlugin(plugin);
}
+
+ for (const plugin of localPlugins) {
+ console.log(`Installing plugin from path: ${plugin}`);
+ await linkInstaller.installFromPath(plugin);
+ }
}
(async () => {
diff --git a/bin/package.json b/bin/package.json
index a39797a8b..cad038d99 100644
--- a/bin/package.json
+++ b/bin/package.json
@@ -1,6 +1,6 @@
{
"name": "bin",
- "version": "2.0.1",
+ "version": "2.0.2",
"description": "",
"main": "checkAllPads.js",
"directories": {
@@ -11,13 +11,13 @@
"ep_etherpad-lite": "workspace:../src",
"log4js": "^6.9.1",
"semver": "^7.6.0",
- "tsx": "^4.7.1",
+ "tsx": "^4.7.2",
"ueberdb2": "^4.2.63"
},
"devDependencies": {
- "@types/node": "^20.11.27",
+ "@types/node": "^20.12.5",
"@types/semver": "^7.5.8",
- "typescript": "^5.4.2"
+ "typescript": "^5.4.4"
},
"scripts": {
"checkPad": "node --import tsx checkPad.ts",
diff --git a/bin/run.sh b/bin/run.sh
index 654897fa4..c6c4c92c9 100755
--- a/bin/run.sh
+++ b/bin/run.sh
@@ -22,7 +22,7 @@ Please type 'Etherpad rocks my socks' (or restart with the '--root'
argument) if you still want to start it as root:
EOF
printf "> " >&2
- read rocks
+ read -r rocks
[ "$rocks" = "Etherpad rocks my socks" ] || fatal "Your input was incorrect"
fi
@@ -32,9 +32,11 @@ bin/installDeps.sh "$@" || exit 1
## Create the admin ui
if [ -z "$NODE_ENV" ] || [ "$NODE_ENV" = "development" ]; then
- ADMIN_UI_PATH="$(dirname $0)/../admin"
+ ADMIN_UI_PATH="$(dirname "$0")/../admin"
+ UI_PATH="$(dirname "$0")/../ui"
log "Creating the admin UI..."
- (cd $ADMIN_UI_PATH && pnpm run build)
+ (cd "$ADMIN_UI_PATH" && pnpm run build)
+ (cd "$UI_PATH" && pnpm run build)
else
log "Cannot create the admin UI in production mode"
fi
diff --git a/doc/.gitignore b/doc/.gitignore
new file mode 100644
index 000000000..4c6f9986d
--- /dev/null
+++ b/doc/.gitignore
@@ -0,0 +1,2 @@
+.vitepress/cache
+dist
diff --git a/doc/.vitepress/config.mts b/doc/.vitepress/config.mts
new file mode 100644
index 000000000..170f21898
--- /dev/null
+++ b/doc/.vitepress/config.mts
@@ -0,0 +1,78 @@
+import { defineConfig } from 'vitepress'
+import {version} from '../../package.json'
+// https://vitepress.dev/reference/site-config
+const commitRef = process.env.COMMIT_REF?.slice(0, 8) || 'dev'
+
+
+export default defineConfig({
+ title: "Etherpad Documentation",
+ description: "Next Generation Collaborative Document Editing",
+ base: '/',
+ themeConfig: {
+ search: {
+ provider: 'local'
+ },
+ // https://vitepress.dev/reference/default-theme-config
+ nav: [
+ { text: 'Home', link: '/' },
+ { text: 'Getting started', link: '/docker.md' }
+ ],
+ logo:'/favicon.ico',
+
+ sidebar: {
+ '/': [
+ {
+ link: '/',
+ text: 'About',
+ items: [
+ { text: 'Docker', link: '/docker.md' },
+ { text: 'Localization', link: '/localization.md' },
+ { text: 'Cookies', link: '/cookies.md' },
+ { text: 'Plugins', link: '/plugins.md' },
+ { text: 'Stats', link: '/stats.md' },
+ {text: 'Skins', link: '/skins.md' },
+ {text: 'Demo', link: '/demo.md' },
+ ]
+ },
+ {
+ text: 'API',
+ link: '/api/',
+ items: [
+ { text: 'Changeset', link: '/api/changeset_library.md' },
+ {text: 'Editbar', link: '/api/editbar.md' },
+ {text: 'EditorInfo', link: '/api/editorInfo.md' },
+ {text: 'Embed Parameters', link: '/api/embed_parameters.md' },
+ {text: 'Hooks Client Side', link: '/api/hooks_client-side.md' },
+ {text: 'Hooks Server Side', link: '/api/hooks_server-side.md' },
+ {text: 'Plugins', link: '/api/pluginfw.md' },
+ {text: 'Toolbar', link: '/api/toolbar.md' },
+ {text: 'HTTP API', link: '/api/http_api.md' },
+ ]
+ },
+ {
+ text: 'Old Docs',
+ items: [
+ { text: 'Easysync description', link: '/etherpad-lite/easysync/easysync-full-description.pdf' },
+ { text: 'Easysync notes', link: '/etherpad-lite/easysync/easysync-notes.pdf' }
+ ]
+ }
+ ],
+ '/stats': [
+ {
+ text: 'Stats',
+ items:[
+ { text: 'Stats', link: '/stats/' }
+ ]
+ }
+ ]
+ },
+ footer: {
+ message: `Published under Apache License`,
+ copyright: `(${commitRef}) v${version} by Etherpad Foundation`
+ },
+
+ socialLinks: [
+ { icon: 'github', link: 'https://github.com/ether/etherpad-lite' }
+ ]
+ }
+})
diff --git a/doc/.vitepress/theme/components/SvgImage.vue b/doc/.vitepress/theme/components/SvgImage.vue
new file mode 100644
index 000000000..344098803
--- /dev/null
+++ b/doc/.vitepress/theme/components/SvgImage.vue
@@ -0,0 +1,22 @@
+
+
+
+
+
+
+
diff --git a/doc/.vitepress/theme/index.ts b/doc/.vitepress/theme/index.ts
new file mode 100644
index 000000000..b7c35ce47
--- /dev/null
+++ b/doc/.vitepress/theme/index.ts
@@ -0,0 +1,12 @@
+import { h } from 'vue'
+import type { Theme } from 'vitepress'
+import DefaultTheme from 'vitepress/theme'
+import './styles/vars.css'
+import SvgImage from './components/SvgImage.vue'
+
+export default {
+ extends: DefaultTheme,
+ enhanceApp({ app }) {
+ app.component('SvgImage', SvgImage)
+ },
+} satisfies Theme
diff --git a/doc/.vitepress/theme/styles/vars.css b/doc/.vitepress/theme/styles/vars.css
new file mode 100644
index 000000000..cc59c1443
--- /dev/null
+++ b/doc/.vitepress/theme/styles/vars.css
@@ -0,0 +1,77 @@
+/**
+ * Colors
+ * -------------------------------------------------------------------------- */
+
+:root {
+ --vp-c-brand: #646cff;
+ --vp-c-brand-light: #747bff;
+ --vp-c-brand-lighter: #9499ff;
+ --vp-c-brand-lightest: #bcc0ff;
+ --vp-c-brand-dark: #535bf2;
+ --vp-c-brand-darker: #454ce1;
+ --vp-c-brand-dimm: rgba(100, 108, 255, 0.08);
+}
+
+/**
+ * Component: Button
+ * -------------------------------------------------------------------------- */
+
+:root {
+ --vp-button-brand-border: var(--vp-c-brand-light);
+ --vp-button-brand-text: var(--vp-c-white);
+ --vp-button-brand-bg: var(--vp-c-brand);
+ --vp-button-brand-hover-border: var(--vp-c-brand-light);
+ --vp-button-brand-hover-text: var(--vp-c-white);
+ --vp-button-brand-hover-bg: var(--vp-c-brand-light);
+ --vp-button-brand-active-border: var(--vp-c-brand-light);
+ --vp-button-brand-active-text: var(--vp-c-white);
+ --vp-button-brand-active-bg: var(--vp-button-brand-bg);
+}
+
+/**
+ * Component: Home
+ * -------------------------------------------------------------------------- */
+
+:root {
+ --vp-home-hero-name-color: transparent;
+ --vp-home-hero-name-background: -webkit-linear-gradient(
+ 120deg,
+ #0f775b 30%,
+ #0f775b
+ );
+
+ --vp-home-hero-image-background-image: linear-gradient(
+ -45deg,
+ #0f775b 50%,
+ #0f775b 50%
+ );
+ --vp-home-hero-image-filter: blur(40px);
+}
+
+@media (min-width: 640px) {
+ :root {
+ --vp-home-hero-image-filter: blur(56px);
+ }
+}
+
+@media (min-width: 960px) {
+ :root {
+ --vp-home-hero-image-filter: blur(72px);
+ }
+}
+
+/**
+ * Component: Custom Block
+ * -------------------------------------------------------------------------- */
+
+:root {
+ --vp-custom-block-tip-border: var(--vp-c-brand);
+ --vp-custom-block-tip-text: var(--vp-c-brand-darker);
+ --vp-custom-block-tip-bg: var(--vp-c-brand-dimm);
+}
+
+.dark {
+ --vp-custom-block-tip-border: var(--vp-c-brand);
+ --vp-custom-block-tip-text: var(--vp-c-brand-lightest);
+ --vp-custom-block-tip-bg: var(--vp-c-brand-dimm);
+}
diff --git a/doc/api/changeset_library.md b/doc/api/changeset_library.md
new file mode 100644
index 000000000..7929aa48b
--- /dev/null
+++ b/doc/api/changeset_library.md
@@ -0,0 +1,44 @@
+# Changeset Library
+
+The [changeset
+library](https://github.com/ether/etherpad-lite/blob/develop/src/static/js/Changeset.js)
+provides tools to create, read, and apply changesets.
+
+## Changeset
+
+```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,
+which relays it to the other users and saves a copy (so that every past revision
+is accessible).
+
+A transmitted changeset looks like this:
+
+```
+'Z:z>1|2=m=b*0|1+1$\n'
+```
+
+## Attribute Pool
+
+```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).
+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
+
+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)
diff --git a/doc/api/editbar.md b/doc/api/editbar.md
new file mode 100644
index 000000000..58f5e70f9
--- /dev/null
+++ b/doc/api/editbar.md
@@ -0,0 +1,36 @@
+# Editbar
+
+Located in `src/static/js/pad_editbar.js`
+
+## isEnabled()
+
+If the editorbar contains the class `enabledtoolbar`, it is enabled.
+
+
+## disable()
+
+Disables the editorbar. This is done by adding the class `disabledtoolbar` and removing the enabledtoolbar
+
+## toggleDropDown(dropdown)
+
+Shows the dropdown `div.popup` whose `id` equals `dropdown`.
+
+## 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)
+Creates an ace callstack and calls the callback with an ace instance (and a toolbar item, if applicable): `callback(cmd, ace, item)`.
+
+Example:
+```
+toolbar.registerAceCommand("insertorderedlist", function (cmd, ace) {
+ ace.ace_doInsertOrderedList();
+});
+```
+
+## registerDropdownCommand(cmd, dropdown)
+Ties a `div.popup` where `id` equals `dropdown` to a `command` fired by clicking a button.
+
+## triggerCommand(cmd[, item])
+Triggers a command (optionally with some internal representation of the toolbar item that triggered it).
diff --git a/doc/api/editorInfo.md b/doc/api/editorInfo.md
new file mode 100644
index 000000000..7b3c27153
--- /dev/null
+++ b/doc/api/editorInfo.md
@@ -0,0 +1,208 @@
+# EditorInfo
+
+Location: `src/static/js/ace2_inner.js`
+
+## editorInfo.ace_replaceRange(start, end, text)
+This function replaces a range (from `start` to `end`) with `text`.
+
+## editorInfo.ace_getRep()
+
+Returns the `rep` object. The rep object consists of the following properties:
+
+- `lines`: Implemented as a skip list
+- `selStart`: The start of the selection
+- `selEnd`: The end of the selection
+- `selFocusAtStart`: Whether the selection is focused at the start
+- `alltext`: The entire text of the document
+- `alines`: The entire text of the document, split into lines
+- `apool`: The pool of attributes
+
+## editorInfo.ace_getAuthor()
+
+Returns the authors of the pad. If the pad has no authors, it returns an empty object.
+
+
+## editorInfo.ace_inCallStack()
+
+Returns true if the editor is in the call stack.
+
+## editorInfo.ace_inCallStackIfNecessary(?)
+
+Executes the function if the editor is in the call stack.
+
+## editorInfo.ace_focus(?)
+
+Focuses the editor.
+
+## editorInfo.ace_importText(?)
+
+Imports text into the editor.
+
+## editorInfo.ace_importAText(?)
+
+Imports text and attributes into the editor.
+
+## editorInfo.ace_exportText(?)
+
+Exports the text from the editor.
+
+## editorInfo.ace_editorChangedSize(?)
+
+Changes the size of the editor.
+
+## editorInfo.ace_setOnKeyPress(?)
+
+Sets the key press event.
+
+## editorInfo.ace_setOnKeyDown(?)
+
+Sets the key down event.
+
+## editorInfo.ace_setNotifyDirty(?)
+
+Sets the dirty notification.
+
+## editorInfo.ace_dispose(?)
+
+Disposes the editor.
+
+## editorInfo.ace_setEditable(bool)
+
+Sets the editor to be editable or not.
+
+## editorInfo.ace_execCommand(?)
+
+Executes a command.
+
+## editorInfo.ace_callWithAce(fn, callStack, normalize)
+
+Calls a function with the ace instance.
+
+## editorInfo.ace_setProperty(key, value)
+
+Sets a property.
+
+## editorInfo.ace_setBaseText(txt)
+
+Sets the base text.
+
+## editorInfo.ace_setBaseAttributedText(atxt, apoolJsonObj)
+
+Sets the base attributed text.
+
+## editorInfo.ace_applyChangesToBase(c, optAuthor, apoolJsonObj)
+
+Applies changes to the base.
+
+## editorInfo.ace_prepareUserChangeset()
+
+Prepares the user changeset.
+
+## editorInfo.ace_applyPreparedChangesetToBase()
+
+Applies the prepared changeset to the base.
+
+## editorInfo.ace_setUserChangeNotificationCallback(f)
+
+Sets the user change notification callback.
+
+## editorInfo.ace_setAuthorInfo(author, info)
+
+Sets the author info.
+
+## editorInfo.ace_fastIncorp(?)
+
+Incorporates changes quickly.
+
+## editorInfo.ace_isCaret(?)
+
+Returns true if the caret is at the specified position.
+
+## editorInfo.ace_getLineAndCharForPoint(?)
+
+Returns the line and character for a point.
+
+## editorInfo.ace_performDocumentApplyAttributesToCharRange(?)
+
+Applies attributes to a character range.
+
+## 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(?)
+
+Toggles an attribute on the current range.
+
+## 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(?)
+
+Performs a selection change.
+
+## editorInfo.ace_doIndentOutdent(?)
+
+Indents or outdents the selection.
+
+## editorInfo.ace_doUndoRedo(?)
+
+Undoes or redoes the last action.
+
+## editorInfo.ace_doInsertUnorderedList(?)
+
+Inserts an unordered list.
+
+## editorInfo.ace_doInsertOrderedList(?)
+
+Inserts an ordered list.
+
+## editorInfo.ace_performDocumentApplyAttributesToRange()
+
+Applies attributes to a range.
+
+## 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(?)
+
+Returns true if the character is a word character.
diff --git a/doc/api/embed_parameters.md b/doc/api/embed_parameters.md
new file mode 100644
index 000000000..8d9f8ac22
--- /dev/null
+++ b/doc/api/embed_parameters.md
@@ -0,0 +1,75 @@
+# 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.
+
+```
+
+```
+
+## showLineNumbers
+* Boolean
+
+Default: true
+
+## showControls
+* Boolean
+
+Default: true
+
+## showChat
+* Boolean
+
+Default: true
+
+## useMonospaceFont
+* Boolean
+
+Default: false
+
+## userName
+* String
+
+Default: "unnamed"
+
+Example: `userName=Etherpad%20User`
+
+## userColor
+* String (css hex color value)
+
+Default: randomly chosen by pad server
+
+Example: `userColor=%23ff9900`
+
+## noColors
+* Boolean
+
+Default: false
+
+## alwaysShowChat
+* Boolean
+
+Default: false
+
+## lang
+* String
+
+Default: en
+
+Example: `lang=ar` (translates the interface into Arabic)
+
+## rtl
+* Boolean
+
+Default: true
+Displays pad text from right to left.
+
+## #L
+* Int
+
+Default: 0
+Focuses pad at specific line number and places caret at beginning of this line
+Special note: Is not a URL parameter but instead of a Hash value
+
diff --git a/doc/api/hooks_client-side.adoc b/doc/api/hooks_client-side.adoc
index e88737cce..9b0e0d18c 100644
--- a/doc/api/hooks_client-side.adoc
+++ b/doc/api/hooks_client-side.adoc
@@ -4,7 +4,7 @@ Most of these hooks are called during or in order to set up the formatting
process.
=== documentReady
-Called from: src/templates/pad.html
+Called from: `src/templates/pad.html`
Things in context:
@@ -14,7 +14,7 @@ This hook proxies the functionality of jQuery's `$(document).ready` event.
=== aceDomLinePreProcessLineAttributes
-Called from: src/static/js/domline.js
+Called from: `src/static/js/domline.js`
Things in context:
@@ -36,7 +36,7 @@ more.
=== aceDomLineProcessLineAttributes
-Called from: src/static/js/domline.js
+Called from: `src/static/js/domline.js`
Things in context:
@@ -58,7 +58,7 @@ more.
=== aceCreateDomLine
-Called from: src/static/js/domline.js
+Called from: `src/static/js/domline.js`
Things in context:
@@ -78,7 +78,7 @@ question, and cls will be the new class of the element going forward.
=== acePostWriteDomLineHTML
-Called from: src/static/js/domline.js
+Called from: `src/static/js/domline.js`
Things in context:
@@ -89,7 +89,7 @@ page.
=== aceAttribsToClasses
-Called from: src/static/js/linestylefilter.js
+Called from: `src/static/js/linestylefilter.js`
Things in context:
@@ -107,7 +107,7 @@ be parsed into a valid class string.
=== aceAttribClasses
-Called from: src/static/js/linestylefilter.js
+Called from: `src/static/js/linestylefilter.js`
Things in context:
1. Attributes - Object of Attributes
@@ -127,7 +127,7 @@ exports.aceAttribClasses = function(hook_name, attr, cb){
=== aceGetFilterStack
-Called from: src/static/js/linestylefilter.js
+Called from: `src/static/js/linestylefilter.js`
Things in context:
@@ -143,7 +143,7 @@ later used by the aceCreateDomLine hook (documented above).
=== aceEditorCSS
-Called from: src/static/js/ace.js
+Called from: `src/static/js/ace.js`
Things in context: None
@@ -152,7 +152,7 @@ should be an array of resource urls or paths relative to the plugins directory.
=== aceInitInnerdocbodyHead
-Called from: src/static/js/ace.js
+Called from: `src/static/js/ace.js`
Things in context:
@@ -165,7 +165,7 @@ editor HTML document.
=== aceEditEvent
-Called from: src/static/js/ace2_inner.js
+Called from: `src/static/js/ace2_inner.js`
Things in context:
@@ -182,7 +182,7 @@ your plugin) that use the information provided by the edit event.
=== aceRegisterNonScrollableEditEvents
-Called from: src/static/js/ace2_inner.js
+Called from: `src/static/js/ace2_inner.js`
Things in context: None
@@ -203,7 +203,7 @@ exports.aceRegisterNonScrollableEditEvents = function(){
=== aceRegisterBlockElements
-Called from: src/static/js/ace2_inner.js
+Called from: `src/static/js/ace2_inner.js`
Things in context: None
@@ -213,7 +213,7 @@ call for those elements.
=== aceInitialized
-Called from: src/static/js/ace2_inner.js
+Called from: `src/static/js/ace2_inner.js`
Things in context:
@@ -228,7 +228,7 @@ use in formatting hooks.
=== postAceInit
-Called from: src/static/js/pad.js
+Called from: `src/static/js/pad.js`
Things in context:
@@ -240,7 +240,7 @@ Things in context:
=== postToolbarInit
-Called from: src/static/js/pad_editbar.js
+Called from: `src/static/js/pad_editbar.js`
Things in context:
@@ -255,14 +255,14 @@ Usage examples:
=== postTimesliderInit
-Called from: src/static/js/timeslider.js
+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
-Called from: src/static/js/broadcast.js
+Called from: `src/static/js/broadcast.js`
Things in context:
@@ -274,7 +274,7 @@ be any example available of this particular hook being used.
=== userJoinOrUpdate
-Called from: src/static/js/pad_userlist.js
+Called from: `src/static/js/pad_userlist.js`
Things in context:
diff --git a/doc/api/hooks_client-side.md b/doc/api/hooks_client-side.md
new file mode 100644
index 000000000..e7d039e50
--- /dev/null
+++ b/doc/api/hooks_client-side.md
@@ -0,0 +1,527 @@
+# Client-side hooks
+
+Most of these hooks are called during or in order to set up the formatting
+process.
+
+## documentReady
+Called from: `src/templates/pad.html`
+
+Things in context:
+
+nothing
+
+This hook proxies the functionality of jQuery's `$(document).ready` event.
+
+## aceDomLinePreProcessLineAttributes
+
+Called from: `src/static/js/domline.js`
+
+Things in context:
+
+1. domline - The current DOM line being processed
+2. cls - The class of the current block element (useful for styling)
+
+This hook is called for elements in the DOM that have the "lineMarkerAttribute"
+set. You can add elements into this category with the aceRegisterBlockElements
+hook above. This hook is run BEFORE the numbered and ordered lists logic is
+applied.
+
+The return value of this hook should have the following structure:
+
+`{ preHtml: String, postHtml: String, processedMarker: Boolean }`
+
+The preHtml and postHtml values will be added to the HTML display of the
+element, and if processedMarker is true, the engine won't try to process it any
+more.
+
+## aceDomLineProcessLineAttributes
+
+Called from: `src/static/js/domline.js`
+
+Things in context:
+
+1. domline - The current DOM line being processed
+2. cls - The class of the current block element (useful for styling)
+
+This hook is called for elements in the DOM that have the "lineMarkerAttribute"
+set. You can add elements into this category with the aceRegisterBlockElements
+hook above. This hook is run AFTER the ordered and numbered lists logic is
+applied.
+
+The return value of this hook should have the following structure:
+
+`{ preHtml: String, postHtml: String, processedMarker: Boolean }`
+
+The preHtml and postHtml values will be added to the HTML display of the
+element, and if processedMarker is true, the engine won't try to process it any
+more.
+
+## aceCreateDomLine
+
+Called from: `src/static/js/domline.js`
+
+Things in context:
+
+1. domline - the current DOM line being processed
+2. cls - The class of the current element (useful for styling)
+
+This hook is called for any line being processed by the formatting engine,
+unless the aceDomLineProcessLineAttributes hook from above returned true, in
+which case this hook is skipped.
+
+The return value of this hook should have the following structure:
+
+`{ extraOpenTags: String, extraCloseTags: String, cls: String }`
+
+extraOpenTags and extraCloseTags will be added before and after the element in
+question, and cls will be the new class of the element going forward.
+
+## acePostWriteDomLineHTML
+
+Called from: `src/static/js/domline.js`
+
+Things in context:
+
+1. node - the DOM node that just got written to the page
+
+This hook is for right after a node has been fully formatted and written to the
+page.
+
+## aceAttribsToClasses
+
+Called from: `src/static/js/linestylefilter.js`
+
+Things in context:
+
+1. linestylefilter - the JavaScript object that's currently processing the ace
+ attributes
+2. key - the current attribute being processed
+3. value - the value of the attribute being processed
+
+This hook is called during the attribute processing procedure, and should be
+used to translate key, value pairs into valid HTML classes that can be inserted
+into the DOM.
+
+The return value for this function should be a list of classes, which will then
+be parsed into a valid class string.
+
+## aceAttribClasses
+
+Called from: `src/static/js/linestylefilter.js`
+
+Things in context:
+1. Attributes - Object of Attributes
+
+This hook is called when attributes are investigated on a line. It is useful if
+you want to add another attribute type or property type to a pad.
+
+Example:
+```
+exports.aceAttribClasses = function(hook_name, attr, cb){
+ attr.sub = 'tag:sub';
+ cb(attr);
+}
+```
+
+## aceGetFilterStack
+
+Called from: `src/static/js/linestylefilter.js`
+
+Things in context:
+
+1. linestylefilter - the JavaScript object that's currently processing the ace
+ attributes
+2. browser - an object indicating which browser is accessing the page
+
+This hook is called to apply custom regular expression filters to a set of
+styles. The one example available is the ep_linkify plugin, which adds internal
+links. They use it to find the telltale `[[ ]]` syntax that signifies internal
+links, and finding that syntax, they add in the internalHref attribute to be
+later used by the aceCreateDomLine hook (documented above).
+
+## aceEditorCSS
+
+Called from: `src/static/js/ace.js`
+
+Things in context: None
+
+This hook is provided to allow custom CSS files to be loaded. The return value
+should be an array of resource urls or paths relative to the plugins directory.
+
+## aceInitInnerdocbodyHead
+
+Called from: `src/static/js/ace.js`
+
+Things in context:
+
+1. iframeHTML - the HTML of the editor iframe up to this point, in array format
+
+This hook is called during the creation of the editor HTML. The array should
+have lines of HTML added to it, giving the plugin author a chance to add in
+meta, script, link, and other tags that go into the `` element of the
+editor HTML document.
+
+## aceEditEvent
+
+Called from: `src/static/js/ace2_inner.js`
+
+Things in context:
+
+1. callstack - a bunch of information about the current action
+2. editorInfo - information about the user who is making the change
+3. rep - information about where the change is being made
+4. documentAttributeManager - information about attributes in the document (this
+ is a mystery to me)
+
+This hook is made available to edit the edit events that might occur when
+changes are made. Currently you can change the editor information, some of the
+meanings of the edit, and so on. You can also make internal changes (internal to
+your plugin) that use the information provided by the edit event.
+
+## aceRegisterNonScrollableEditEvents
+
+Called from: `src/static/js/ace2_inner.js`
+
+Things in context: None
+
+When aceEditEvent (documented above) finishes processing the event, it scrolls
+the viewport to make caret visible to the user, but if you don't want that
+behavior to happen you can use this hook to register which edit events should
+not scroll viewport. The return value of this hook should be a list of event
+names.
+
+Example:
+```
+exports.aceRegisterNonScrollableEditEvents = function(){
+ return [ 'repaginate', 'updatePageCount' ];
+}
+```
+
+## aceRegisterBlockElements
+
+Called from: `src/static/js/ace2_inner.js`
+
+Things in context: None
+
+The return value of this hook will add elements into the "lineMarkerAttribute"
+category, making the aceDomLineProcessLineAttributes hook (documented below)
+call for those elements.
+
+## aceInitialized
+
+Called from: `src/static/js/ace2_inner.js`
+
+Things in context:
+
+1. editorInfo - information about the user who will be making changes through
+ the interface, and a way to insert functions into the main ace object (see
+ ep_headings)
+2. rep - information about where the user's cursor is
+3. documentAttributeManager - some kind of magic
+
+This hook is for inserting further information into the ace engine, for later
+use in formatting hooks.
+
+## postAceInit
+
+Called from: `src/static/js/pad.js`
+
+Things in context:
+
+1. ace - the ace object that is applied to this editor.
+2. clientVars - Object containing client-side configuration such as author ID
+ and plugin settings. Your plugin can manipulate this object via the
+ `clientVars` server-side hook.
+3. pad - the pad object of the current pad.
+
+## postToolbarInit
+
+Called from: `src/static/js/pad_editbar.js`
+
+Things in context:
+
+1. ace - the ace object that is applied to this editor.
+2. toolbar - Editbar instance. See below for the Editbar documentation.
+
+Can be used to register custom actions to the toolbar.
+
+Usage examples:
+
+* [https://github.com/tiblu/ep_authorship_toggle]()
+
+## 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
+
+Called from: `src/static/js/broadcast.js`
+
+Things in context:
+
+1. rev - The newRevision
+
+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
+
+Called from: `src/static/js/pad_userlist.js`
+
+Things in context:
+
+1. info - the user information
+
+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`
+
+Called from: `src/static/js/chat.js`
+
+This hook runs on the client side whenever a chat message is received from the
+server. It can be used to create different notifications for chat messages. Hook
+functions can modify the `author`, `authorName`, `duration`, `rendered`,
+`sticky`, `text`, and `timeStr` context properties to change how the message is
+processed. The `text` and `timeStr` properties may contain HTML and come
+pre-sanitized; plugins should be careful to sanitize any added user input to
+avoid introducing an XSS vulnerability.
+
+Context properties:
+
+* `authorName`: The display name of the user that wrote the message.
+* `author`: The author ID of the user that wrote the message.
+* `text`: Sanitized message HTML, with URLs wrapped like `url`. (Note that `message.text` is not sanitized or processed
+ in any way.)
+* `message`: The raw message object as received from the server, except with
+ time correction and a default `authorId` property if missing. Plugins must not
+ modify this object. Warning: Unlike `text`, `message.text` is not
+ pre-sanitized or processed in any way.
+* `rendered` - Used to override the default message rendering. Initially set to
+ `null`. If the hook function sets this to a DOM element object or a jQuery
+ object, then that object will be used as the rendered message UI. Otherwise,
+ if this is set to `null`, then Etherpad will render a default UI for the
+ message using the other context properties.
+* `sticky` (boolean): Whether the gritter notification should fade out on its
+ own or just sit there until manually closed.
+* `timestamp`: When the chat message was sent (milliseconds since epoch),
+ corrected using the difference between the local clock and the server's clock.
+* `timeStr`: The message timestamp as a formatted string.
+* `duration`: How long (in milliseconds) to display the gritter notification (0
+ to disable).
+
+## `chatSendMessage`
+
+Called from: `src/static/js/chat.js`
+
+This hook runs on the client side whenever the user sends a new chat message.
+Plugins can mutate the message object to change the message text or add metadata
+to control how the message will be rendered by the `chatNewMessage` hook.
+
+Context properties:
+
+* `message`: The message object that will be sent to the Etherpad server.
+
+## collectContentPre
+
+Called from: `src/static/js/contentcollector.js`
+
+Things in context:
+
+1. cc - the contentcollector object
+2. state - the current state of the change being made
+3. tname - the tag name of this node currently being processed
+4. styl - the style applied to the node (probably CSS) -- Note the typo
+5. cls - the HTML class string of the node
+
+This hook is called before the content of a node is collected by the usual
+methods. The cc object can be used to do a bunch of things that modify the
+content of the pad. See, for example, the heading1 plugin for etherpad original.
+
+E.g. if you need to apply an attribute to newly inserted characters, call
+cc.doAttrib(state, "attributeName") which results in an attribute
+attributeName=true.
+
+If you want to specify also a value, call cc.doAttrib(state,
+"attributeName::value") which results in an attribute attributeName=value.
+
+
+## collectContentImage
+
+Called from: `src/static/js/contentcollector.js`
+
+Things in context:
+
+1. cc - the contentcollector object
+2. state - the current state of the change being made
+3. tname - the tag name of this node currently being processed
+4. style - the style applied to the node (probably CSS)
+5. cls - the HTML class string of the node
+6. node - the node being modified
+
+This hook is called before the content of an image node is collected by the
+usual methods. The cc object can be used to do a bunch of things that modify the
+content of the pad.
+
+Example:
+
+```
+exports.collectContentImage = function(name, context){
+ context.state.lineAttributes.img = context.node.outerHTML;
+}
+
+```
+
+## collectContentPost
+
+Called from: `src/static/js/contentcollector.js`
+
+Things in context:
+
+1. cc - the contentcollector object
+2. state - the current state of the change being made
+3. tname - the tag name of this node currently being processed
+4. style - the style applied to the node (probably CSS)
+5. cls - the HTML class string of the node
+
+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`
+
+Called from: `src/static/js/collab_client.js`
+
+Things in context:
+
+1. payload - the data that got sent with the message (use it for custom message
+ content)
+
+This hook gets called every time the client receives a message of type `name`.
+This can most notably be used with the new HTTP API call, "sendClientsMessage",
+which sends a custom message type to all clients connected to a pad. You can
+also use this to handle existing types.
+
+`collab_client.js` has a pretty extensive list of message types, if you want to
+take a look.
+
+## aceStartLineAndCharForPoint-aceEndLineAndCharForPoint
+
+Called from: src/static/js/ace2_inner.js
+
+Things in context:
+
+1. callstack - a bunch of information about the current action
+2. editorInfo - information about the user who is making the change
+3. rep - information about where the change is being made
+4. root - the span element of the current line
+5. point - the starting/ending element where the cursor highlights
+6. documentAttributeManager - information about attributes in the document
+
+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
+
+Called from: `src/static/js/ace2_inner.js`
+
+Things in context:
+
+1. callstack - a bunch of information about the current action
+2. editorInfo - information about the user who is making the change
+3. rep - information about where the change is being made
+4. documentAttributeManager - information about attributes in the document
+5. evt - the fired event
+
+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
+
+Called from: `src/static/js/contentcollector.js`
+
+Things in context:
+
+1. cc - the contentcollector object
+2. state - the current state of the change being made
+3. tname - the tag name of this node currently being processed
+4. text - the text for that line
+
+This hook allows you to validate/manipulate the text before it's sent to the
+server side. To change the text, either:
+
+* Set the `text` context property to the desired value and return `undefined`.
+* (Deprecated) Return a string. If a hook function changes the `text` context
+ property, the return value is ignored. If no hook function changes `text` but
+ multiple hook functions return a string, the first one wins.
+
+Example:
+
+```
+exports.collectContentLineText = (hookName, context) => {
+ context.text = tweakText(context.text);
+};
+```
+
+## collectContentLineBreak
+
+Called from: `src/static/js/contentcollector.js`
+
+Things in context:
+
+1. cc - the contentcollector object
+2. state - the current state of the change being made
+3. tname - the tag name of this node currently being processed
+
+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
+
+Called from: `src/static/js/linestylefilter.js`
+
+Things in context:
+
+1. linestylefilter - the JavaScript object that's currently processing the ace
+ attributes
+2. text - the line text
+3. class - line class
+
+This hook is provided to allow whether a given line should be deliniated with
+multiple authors. Multiple authors in one line cause the creation of magic span
+lines. This might not suit you and now you can disable it and handle your own
+deliniation. The return value should be either true(disable) or false.
+
+## aceSetAuthorStyle
+
+Called from: `src/static/js/ace2_inner.js`
+
+Things in context:
+
+1. dynamicCSS - css manager for inner ace
+2. outerDynamicCSS - css manager for outer ace
+3. parentDynamicCSS - css manager for parent document
+4. info - author style info
+5. author - author info
+6. authorSelector - css selector for author span in inner ace
+
+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
+
+Called from: `src/static/js/ace2_inner.js`
+
+Things in context:
+
+1. rep - information about where the user's cursor is
+2. documentAttributeManager - information about attributes in the document
+
+This hook allows a plugin to react to a cursor or selection change,
+perhaps to update a UI element based on the style at the cursor location.
diff --git a/doc/api/hooks_overview.md b/doc/api/hooks_overview.md
new file mode 100644
index 000000000..35a88dbe1
--- /dev/null
+++ b/doc/api/hooks_overview.md
@@ -0,0 +1,117 @@
+# 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
+different plugins.
+
+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
+
+Note: The documentation in this section applies to every hook unless the
+hook-specific documentation says otherwise.
+
+### Arguments
+
+Hook functions are called with three arguments:
+
+1. `hookName` - The name of the hook being invoked.
+2. `context` - An object with some relevant information about the context of the
+ call. See the hook-specific documentation for details.
+3. `cb` - For asynchronous operations this callback can be called to signal
+ completion and optionally provide a return value. The callback takes a single
+ argument, the meaning of which depends on the hook (see the "Return values"
+ section for general information that applies to most hooks). This callback
+ always returns `undefined`.
+
+### 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
+that expect their hook functions to provide a value synchronously. For such
+hooks, the hook functions must do one of the following:
+
+* Call the callback with a non-Promise value (`undefined` is acceptable) and
+ return `undefined`, in that order.
+* Return a non-Promise value other than `undefined` (`null` is acceptable) and
+ never call the callback. Note that `async` functions *always* return a
+ Promise, so they must never be used for synchronous hooks.
+* Only have two parameters (`hookName` and `context`) and return any non-Promise
+ value (`undefined` is acceptable).
+
+For hooks that permit asynchronous behavior, the hook functions must do one or
+more of the following:
+
+* Return `undefined` and call the callback, in either order.
+* Return something other than `undefined` (`null` is acceptable) and never call
+ the callback. Note that `async` functions *always* return a Promise, so they
+ must never call the callback.
+* Only have two parameters (`hookName` and `context`).
+
+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).
+To avoid problems, do not use default or rest parameters when defining hook
+functions.
+
+### Return values
+
+A hook function can provide a value to Etherpad in one of the following ways:
+
+* Pass the desired value as the first argument to the callback.
+* Return the desired value directly. The value must not be `undefined` unless
+ the hook function only has two parameters. (Hook functions with three
+ parameters that want to provide `undefined` should instead use the callback.)
+* For hooks that permit asynchronous behavior, return a Promise that resolves to
+ the desired value.
+* For hooks that permit asynchronous behavior, pass a Promise that resolves to
+ the desired value as the first argument to the callback.
+
+Examples:
+
+```javascript
+exports.exampleOne = (hookName, context, callback) => {
+ return 'valueOne';
+};
+
+exports.exampleTwo = (hookName, context, callback) => {
+ callback('valueTwo');
+ return;
+};
+
+// ONLY FOR HOOKS THAT PERMIT ASYNCHRONOUS BEHAVIOR
+exports.exampleThree = (hookName, context, callback) => {
+ return new Promise('valueThree');
+};
+
+// ONLY FOR HOOKS THAT PERMIT ASYNCHRONOUS BEHAVIOR
+exports.exampleFour = (hookName, context, callback) => {
+ callback(new Promise('valueFour'));
+ return;
+};
+
+// ONLY FOR HOOKS THAT PERMIT ASYNCHRONOUS BEHAVIOR
+exports.exampleFive = async (hookName, context) => {
+ // Note that this function is async, so it actually returns a Promise that
+ // 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.
+Flattening one level makes it possible for a hook function to behave as if it
+were multiple separate hook functions.
+
+For example: Suppose a hook has eight registered functions that return the
+following values: `1`, `[2]`, `['3a', '3b']` `[[4]]`, `undefined`,
+`[undefined]`, `[]`, and `null`. The value returned to the caller of the hook is
+`[1, 2, '3a', '3b', [4], undefined, null]`.
diff --git a/doc/api/hooks_server-side.adoc b/doc/api/hooks_server-side.adoc
index d95d4ec6b..25a696b43 100644
--- a/doc/api/hooks_server-side.adoc
+++ b/doc/api/hooks_server-side.adoc
@@ -2,7 +2,7 @@
These hooks are called on server-side.
=== loadSettings
-Called from: src/node/server.ts
+Called from: `src/node/server.ts`
Things in context:
@@ -11,7 +11,7 @@ Things in context:
Use this hook to receive the global settings in your plugin.
=== shutdown
-Called from: src/node/server.ts
+Called from: `src/node/server.ts`
Things in context: None
@@ -34,7 +34,7 @@ exports.shutdown = async (hookName, context) => {
----
=== pluginUninstall
-Called from: src/static/js/pluginfw/installer.js
+Called from: `src/static/js/pluginfw/installer.js`
Things in context:
@@ -43,7 +43,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
-Called from: src/static/js/pluginfw/installer.js
+Called from: `src/static/js/pluginfw/installer.js`
Things in context:
@@ -123,7 +123,7 @@ Context properties:
=== expressCloseServer
-Called from: src/node/hooks/express.js
+Called from: `src/node/hooks/express.js`
Things in context: Nothing
@@ -142,7 +142,7 @@ exports.expressCloseServer = async () => {
----
=== eejsBlock_``
-Called from: src/node/eejs/index.js
+Called from: `src/node/eejs/index.js`
Things in context:
diff --git a/doc/api/hooks_server-side.md b/doc/api/hooks_server-side.md
new file mode 100644
index 000000000..05a66209f
--- /dev/null
+++ b/doc/api/hooks_server-side.md
@@ -0,0 +1,1103 @@
+# Server-side hooks
+
+These hooks are called on server-side.
+
+## loadSettings
+Called from: `src/node/server.js`
+
+Things in context:
+
+1. settings - the settings object
+
+Use this hook to receive the global settings in your plugin.
+
+## shutdown
+Called from: `src/node/server.js`
+
+Things in context: None
+
+This hook runs before shutdown. Use it to stop timers, close sockets and files,
+flush buffers, etc. The database is not available while this hook is running.
+The shutdown function must not block for long because there is a short timeout
+before the process is forcibly terminated.
+
+The shutdown function must return a Promise, which must resolve to `undefined`.
+Returning `callback(value)` will return a Promise that is resolved to `value`.
+
+Example:
+
+```
+// using an async function
+exports.shutdown = async (hookName, context) => {
+ await flushBuffers();
+};
+```
+
+## pluginUninstall
+Called from: `src/static/js/pluginfw/installer.js`
+
+Things in context:
+
+1. plugin_name - self-explanatory
+
+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
+Called from: `src/static/js/pluginfw/installer.js`
+
+Things in context:
+
+1. plugin_name - self-explanatory
+
+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_`
+
+Called from: `src/static/js/pluginfw/plugins.js`
+
+Run during startup after the named plugin is initialized.
+
+Context properties:
+
+* `logger`: An object with the following `console`-like methods: `debug`,
+ `info`, `log`, `warn`, `error`.
+
+## `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
+added to the Express Application object. Use this hook to add route handlers or
+middleware that executes before `express-session` state is created and
+authentication is performed. This is useful for creating public endpoints that
+don't spam the database with new `express-session` records or trigger
+authentication.
+
+**WARNING:** All handlers registered during this hook run before the built-in
+authentication checks, so any handled endpoints will be public unless the
+handler itself authenticates the user.
+
+Context properties:
+
+* `app`: The Express [Application](https://expressjs.com/en/4x/api.html#app)
+ object.
+
+Example:
+
+```javascript
+exports.expressPreSession = async (hookName, {app}) => {
+ app.get('/hello-world', (req, res) => res.send('hello world'));
+};
+```
+
+## `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
+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)
+ object.
+
+## `expressCreateServer`
+
+Called from: `src/node/hooks/express.js`
+
+Identical to the `expressConfigure` hook (the two run in parallel with each
+other) except this hook's context includes the HTTP Server object.
+
+Context properties:
+
+* `app`: The Express [Application](https://expressjs.com/en/4x/api.html#app)
+ 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.
+
+## expressCloseServer
+
+Called from: `src/node/hooks/express.js`
+
+Things in context: Nothing
+
+This hook is called when the HTTP server is closing, which happens during
+shutdown (see the shutdown hook) and when the server restarts (e.g., when a
+plugin is installed via the `/admin/plugins` page). The HTTP server may or may
+not already be closed when this hook executes.
+
+Example:
+
+```
+exports.expressCloseServer = async () => {
+ await doSomeCleanup();
+};
+```
+
+## eejsBlock_``
+Called from: `src/node/eejs/index.js`
+
+Things in context:
+
+1. content - the content of the block
+
+This hook gets called upon the rendering of an ejs template block. For any specific kind of block, you can change how that block gets rendered by modifying the content object passed in.
+
+Available blocks in `pad.html` are:
+
+* `htmlHead` - after `` and immediately before the title tag
+* `styles` - the style ``s
+* `body` - the contents of the body tag
+* `editbarMenuLeft` - the left tool bar (consider using the toolbar controller instead of manually adding html here)
+* `editbarMenuRight` - right tool bar
+* `afterEditbar` - allows you to add stuff immediately after the toolbar
+* `userlist` - the contents of the userlist dropdown
+* `loading` - the initial loading message
+* `mySettings` - the left column of the settings dropdown ("My view"); intended for adding checkboxes only
+* `mySettings.dropdowns` - add your dropdown settings here
+* `globalSettings` - the right column of the settings dropdown ("Global view")
+* `importColumn` - import form
+* `exportColumn` - export form
+* `modals` - Contains all connectivity messages
+* `embedPopup` - the embed dropdown
+* `scripts` - Add your script tags here, if you really have to (consider use client-side hooks instead)
+
+`timeslider.html` blocks:
+
+* `timesliderStyles`
+* `timesliderScripts`
+* `timesliderBody`
+* `timesliderTop`
+* `timesliderEditbarRight`
+* `modals`
+
+`index.html` blocks:
+
+* `indexCustomStyles` - contains the `index.css` `` tag, allows you to add your own or to customize the one provided by the active skin
+* `indexWrapper` - contains the form for creating new pads
+* `indexCustomScripts` - contains the `index.js` `
+
+
diff --git a/ui/login.html b/ui/login.html
new file mode 100644
index 000000000..0ff588363
--- /dev/null
+++ b/ui/login.html
@@ -0,0 +1,38 @@
+
+
+
+
+
+
+ SSO Etherpad
+
+
+