mirrors/remark42
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

move non-technical part of the readme to site

Browse Source
This commit is contained in:
Dmitry Verkhoturov
2021-10-23 11:37:23 -05:00
committed by Umputun
parent c222b8a2ba
commit aa34dc8384
6 changed files with 61 additions and 450 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+2 -389
View File
@@ -40,208 +40,20 @@ All remark42 documentation is available [by the link](https://remark42.com/docs/
#
- [Install](#install)
- [Backend](#backend)
- [With Docker](#with-docker)
- [Without Docker](#without-docker)
- [Parameters](#parameters)
- [Deprecated parameters](#deprecated-parameters)
- [Required parameters](#required-parameters)
- [Quick installation test](#quick-installation-test)
- [Register OAuth2 providers](#register-oauth2-providers)
- [Facebook Auth provider](#facebook-auth-provider)
- [GitHub Auth provider](#github-auth-provider)
- [Google Auth provider](#google-auth-provider)
- [Microsoft Auth provider](#microsoft-auth-provider)
- [Telegram Auth Provider](#telegram-auth-provider)
- [Twitter Auth provider](#twitter-auth-provider)
- [Yandex Auth provider](#yandex-auth-provider)
- [Patreon Auth provider](#patreon-auth-provider)
- [Anonymous Auth provider](#anonymous-auth-provider)
- [Initial import from Disqus](#initial-import-from-disqus)
- [Initial import from WordPress](#initial-import-from-wordpress)
- [Backup and restore](#backup-and-restore)
- [Automatic backups](#automatic-backups)
- [Manual backup](#manual-backup)
- [Restore from backup](#restore-from-backup)
- [Backup format](#backup-format)
- [Backup format](#backup-format)
- [Admin users](#admin-users)
- [Docker parameters](#docker-parameters)
- [Setup on your website](#setup-on-your-website)
- [Comments](#comments)
- [Last comments](#last-comments)
- [Counter](#counter)
- [Build from the source](#build-from-the-source)
- [Development](#development)
- [Backend development](#backend-development)
- [Frontend development](#frontend-development)
- [Build](#build)
- [Devserver](#devserver)
- [API](#api)
- [Authorization](#authorization)
- [Commenting](#commenting)
- [Streaming API](#streaming-api)
- [RSS feeds](#rss-feeds)
- [Images management](#images-management)
- [Email subscription](#email-subscription)
- [Admin](#admin)
- [Privacy](#privacy)
- [Technical details](#technical-details)
## Install
### Backend
#### With Docker
_this is the recommended way to run Remark42_
* copy provided `docker-compose.yml` and customize for your needs
* make sure you **don't keep** `ADMIN_PASSWD=something...` for any non-development deployments
* pull prepared images from the Docker Hub and start - `docker-compose pull && docker-compose up -d`
* alternatively compile from the sources - `docker-compose build && docker-compose up -d`
#### Without Docker
* download [archive for stable release](https://github.com/umputun/remark42/releases)
* unpack with `gunzip` (Linux, macOS) or with `zip` (Windows)
* run as `remark42.{os}-{arch} server {parameters...}`, i.e. `remark42.linux-amd64 server --secret=12345 --url=http://127.0.0.1:8080`
* alternatively compile from the sources - `make OS=[linux|darwin|windows] ARCH=[amd64,386,arm64,arm]`
#### Quick installation test
To verify if Remark42 has been properly installed, check a demo page at `${REMARK_URL}/web` URL. Make sure to include `remark` site ID to `${SITE}` list.
#### Register OAuth2 providers
Authentication handled by external providers. You should setup OAuth2 for all (or some) of them to allow users to make comments. It is not mandatory to have all of them, but at least one should be correctly configured.
##### Facebook Auth provider
1. From https://developers.facebook.com select **"My Apps"**/**"Add a new App"**
2. Set **"Display Name"** and **"Contact email"**
3. Choose **"Facebook Login"** and then **"Web"**
4. Set "Site URL" to your domain, e.g.: `https://remark42.mysite.com`
5. Under **"Facebook login"**/**"Settings"** fill "Valid OAuth redirect URIs" with your callback URL constructed as domain + `/auth/facebook/callback`
6. Select **"App Review"** and turn public flag on. This step may ask you to provide a link to your privacy policy
##### GitHub Auth provider
1. Create a new **"OAuth App"**: https://github.com/settings/developers
2. Fill **"Application Name"** and **"Homepage URL"** for your site
3. Under **"Authorization callback URL"** enter the correct URL constructed as domain + `/auth/github/callback`, i.e. `https://remark42.mysite.com/auth/github/callback`
4. Take note of the **Client ID** and **Client Secret**
##### Google Auth provider
1. Create a new project: https://console.cloud.google.com/projectcreate
2. Choose the new project from the top right project dropdown (only if another project is selected)
3. In the project Dashboard center pane, choose **"API Manager"**
4. In the left Nav pane, choose **"Credentials"**
5. In the center pane, choose **"OAuth consent screen"** tab. Fill in **"Product name shown to users"** and hit save
6. In the center pane, choose **"Credentials"** tab
* Open the **"New credentials"** drop down
* Choose **"OAuth client ID"**
* Choose **"Web application"**
* Application name is freeform, choose something appropriate
* Authorized origins is your domain, e.g.: `https://remark42.mysite.com`
* Authorized redirect URIs is the location of OAuth2/callback constructed as domain + `/auth/google/callback`, e.g.: `https://remark42.mysite.com/auth/google/callback`
* Choose **"Create"**
7. Take note of the **Client ID** and **Client Secret**
_instructions for Google OAuth2 setup borrowed from [oauth2_proxy](https://github.com/bitly/oauth2_proxy)_
##### Microsoft Auth provider
1. Register a new application [using the Azure portal](https://docs.microsoft.com/en-us/graph/auth-register-app-v2)
2. Under **"Authentication/Platform configurations/Web"** enter the correct URL constructed as domain + `/auth/microsoft/callback`, i.e. `https://example.mysite.com/auth/microsoft/callback`
3. In **"Overview"** take note of the **Application (client) ID**
4. Choose the new project from the top right project dropdown (only if another project is selected)
5. Select **"Certificates & secrets"** and click on **"+ New Client Secret"**
##### Telegram Auth Provider
1. Contact [@BotFather](https://t.me/botfather) and follow his instructions to create your own bot (call it, for example, "My site auth bot")
1. Write down resulting token as `TELEGRAM_TOKEN` into remark42 config, and also set `AUTH_TELEGRAM` to `true` to enable telegram auth for your users.
##### Twitter Auth provider
1. Create a new Twitter application https://developer.twitter.com/en/apps
2. Fill **App name**, **Description** and **URL** of your site
3. In the field **Callback URLs** enter the correct URL of your callback handler, e.g. domain + `/auth/twitter/callback`
4. Under **Key and tokens** take note of the **Consumer API Key** and **Consumer API Secret key**. Those will be used as `AUTH_TWITTER_CID` and `AUTH_TWITTER_CSEC`
##### Yandex Auth provider
1. Create a new **"OAuth App"**: https://oauth.yandex.com/client/new
2. Fill **"App name"** for your site
3. Under **Platforms** select **"Web services"** and enter **"Callback URI #1"** constructed as domain + `/auth/yandex/callback`, i.e. `https://remark42.mysite.com/auth/yandex/callback`
4. Select **Permissions**. You need the following permissions only from the **"Yandex.Passport API"** section:
* Access to the user avatar
* Access to username, first name and surname, gender
5. Fill out the rest of the fields if needed
6. Take note of the **ID** and **Password**
For more details refer to [Yandex OAuth](https://yandex.com/dev/oauth/doc/dg/concepts/about.html) and [Yandex.Passport](https://yandex.com/dev/passport/doc/dg/index.html) API documentation.
##### Patreon Auth provider
1. Create a new Patreon client https://www.patreon.com/portal/registration/register-clients
2. Fill **App Name**, **Description**
3. In the field **Redirect URIs** enter the correct URI constructed as domain + `/auth/patreon/callback`, i.e. `https://example.mysite.com/auth/patreon/callback`
4. Expand client details, take a note of the **Client ID** and **Client Secret**. Those will be used as `AUTH_PATREON_CID` and `AUTH_PATREON_CSEC`
##### Anonymous Auth provider
Optionally, anonymous access can be turned on. In this case, an extra `anonymous` provider will allow logins without any social login with any name satisfying 2 conditions:
* name should be at least 3 characters long
* name has to start from the letter and contains letters, numbers, underscores and spaces only
#### Importing comments
Remark42 supports importing comments from Disqus, WordPress, or native backup format. All imported comments have an `Imported` field set to `true`.
##### Initial import from Disqus
1. Disqus provides an export of all comments on your site in a gzipped file. This option is available in your Moderation panel at Disqus Admin > Setup > Export. The export will be sent into a queue and then emailed to the address associated with your account once it's ready. Direct link to export will be something like `https://<siteud>.disqus.com/admin/discussions/export/`. See [importing-exporting](https://help.disqus.com/en/articles/1717199-importing-exporting) for more details
2. Move this file to your Remark42 host within `./var` and extract, i.e. `gunzip <disqus-export-name>.xml.gz`
3. Run import command - `docker exec -it remark42 import -p disqus -f /srv/var/{disqus-export-name}.xml -s {your site ID}`
##### Initial import from WordPress
1. Use [that instruction](https://wordpress.com/support/export/) to export comments to file using standard WordPress functionality
2. Move this file to your Remark42 host within `./var`
3. Run import command - `docker exec -it remark42 import -p wordpress -f /srv/var/{wordpress-export-name}.xml -s {your site ID}`
##### Initial import from Commento
1. Move exported json file to your Remark42 host within `./var`
2. Run import command - `docker exec -it remark42 import -p commento -f /srv/var/{commento-export-name}.json -s {your site ID}`
#### Backup and restore
##### Automatic backups
Remark42 by default makes daily backup files under `${BACKUP_PATH}` (default `./var/backup`). Backups kept up to `${MAX_BACKUP_FILES}` (default 10). Each backup file contains exported and gzipped content, i.e. all comments. At any point, the user can restore such backup and revert all comments to the desired state.
**Note:** Restore procedure cleans the current data store and replaces all comments with comments from the backup file.
For safety and security reasons restore functionality not exposed outside of your server by default. The recommended way to restore from the backup is to use provided `scripts/restore-backup.sh`. It can run inside the container:
`docker exec -it remark42 restore -f {backup-filename.gz} -s {your site ID}`
##### Manual backup
In addition to automatic backups, user can make a backup manually. This command makes `userbackup-{site ID}-{timestamp}.gz` by default.
`docker exec -it remark42 backup -s {your site ID}`
##### Restore from backup
Restore will clean all comments first and then will process with complete import from a given file.
`docker exec -it remark42 restore -f {backup file name} -s {your site ID}`
##### Backup format
#### Backup format
The backup file is a text file with all exported comments separated by EOL. Each backup record is a valid JSON with all key/value unmarshaled from `Comment` struct (see below).
@@ -287,211 +99,12 @@ services:
- ./var:/srv/var # persistent volume to store all Remark42 data
```
### Setup on your website
#### Comments
It's the main widget that renders a list of comments.
Add this snippet to the bottom of web page:
```html
<script>
var remark_config = {
host: "REMARK_URL", // hostname of Remark42 server, same as REMARK_URL in backend config, e.g. "https://demo.remark42.com"
site_id: 'YOUR_SITE_ID',
components: ['embed'], // optional param; which components to load. default to ["embed"]
// to load all components define components as ['embed', 'last-comments', 'counter']
// available component are:
// - 'embed': basic comments widget
// - 'last-comments': last comments widget, see `Last Comments` section below
// - 'counter': counter widget, see `Counter` section below
url: 'PAGE_URL', // optional param; if it isn't defined
// `window.location.origin + window.location.pathname` will be used
//
// Note that if you use query parameters as significant part of URL
// (the one that actually changes content on page)
// you will have to configure URL manually to keep query params, as
// `window.location.origin + window.location.pathname` doesn't contain query params and
// hash. For example, default URL for `https://example/com/example-post?id=1#hash`
// would be `https://example/com/example-post`
//
// The problem with query params is that they often contain useless params added by
// various trackers (utm params) and doesn't have defined order, so Remark42 treats differently
// all this examples:
// https://example.com/?postid=1&date=2007-02-11
// https://example.com/?date=2007-02-11&postid=1
// https://example.com/?date=2007-02-11&postid=1&utm_source=google
//
// If you deal with query parameters make sure you pass only significant part of it
// in well defined order
max_shown_comments: 10, // optional param; if it isn't defined default value (15) will be used
theme: 'dark', // optional param; if it isn't defined default value ('light') will be used
page_title: 'Moving to Remark42', // optional param; if it isn't defined `document.title` will be used
locale: 'en', // set up locale and language, if it isn't defined default value ('en') will be used
show_email_subscription: false, // optional param; by default it is `true` and you can see email subscription feature
// in interface when enable it from backend side
// if you set this param in `false` you will get notifications email notifications as admin
// but your users won't have interface for subscription
simple_view: false // optional param; overrides the parameter from the backend
// minimized UI with basic info only
};
</script>
<script>!function(e,n){for(var o=0;o<e.length;o++){var r=n.createElement("script"),c=".js",d=n.head||n.body;"noModule"in r?(r.type="module",c=".mjs"):r.async=!0,r.defer=!0,r.src=remark_config.host+"/web/"+e[o]+c,d.appendChild(r)}}(remark_config.components||["embed"],document);</script>
```
And then add this node in the place where you want to see Remark42 widget:
```html
<div id="remark42"></div>
```
After that widget will be rendered inside this node.
If you want to set this up on a Single Page App, see [appropriate doc page](site/src/docs/configuration/frontend/index.md).
##### Themes
Right now Remark42 has two themes: light and dark. You can pick one using a configuration object, but there is also a possibility to switch between themes in runtime. For this purpose Remark42 adds to `window` object named `REMARK42`, which contains a function `changeTheme`. Just call this function and pass a name of the theme that you want to turn on:
```js
window.REMARK42.changeTheme('light');
```
##### Locales
Right now Remark42 is translated to English (en), Belarusian (be), Brazilian Portuguese (bp), Bulgarian (bg), Chinese (zh), Finnish (fi), French (fr), German (de), Japanese (ja), Korean (ko), Polish (pl), Russian (ru), Spanish (es), Turkish (tr), Ukrainian (ua), Italian (it) and Vietnamese (vi) languages. You can pick one using [configuration object](#setup-on-your-website).
Do you want to translate Remark42 to other locales? Please see [this documentation](site/src/docs/contributing/translations/index.md) for details.
#### Last comments
It's a widget that renders the list of last comments from your site.
Add this snippet to the bottom of web page, or adjust already present `remark_config` to have `last-comments` in `components` list:
```html
<script>
var remark_config = {
host: "REMARK_URL", // hostname of Remark42 server, same as REMARK_URL in backend config, e.g. "https://demo.remark42.com"
site_id: 'YOUR_SITE_ID',
components: ['last-comments']
};
</script>
```
And then add this node in the place where you want to see last comments widget:
```html
<div class="remark42__last-comments" data-max="50"></div>
```
`data-max` sets the max amount of comments (default: `15`).
#### Counter
It's a widget that renders several comments for the specified page.
Add this snippet to the bottom of web page, or adjust already present `remark_config` to have `counter` in `components` list:
```html
<script>
var remark_config = {
host: "REMARK_URL", // hostname of Remark42 server, same as REMARK_URL in backend config, e.g. "https://demo.remark42.com"
site_id: 'YOUR_SITE_ID',
components: ['counter']
};
</script>
```
And then add a node like this in the place where you want to see a number of comments:
```html
<span class="remark42__counter" data-url="https://domain.com/path/to/article/"></span>
```
You can use as many nodes like this as you need to. The script will found all of them by the class `remark__counter`, and it will use `data-url` attribute to define the page with comments.
Also script can use `url` property from `remark_config` object, or `window.location.origin + window.location.pathname` if nothing else is defined.
## Build from the source
* to build Docker container - `make docker`. This command will produce container `umputun/remark42`
* to build a single binary for direct execution - `make OS=<linux|windows|darwin> ARCH=<amd64|386>`. This step will produce executable
`remark42` file with everything embedded
## Development
You can use a fully functional local version to develop and test both frontend and backend. It requires at least 2GB RAM or swap enabled.
To bring it up run:
```bash
# if you mainly work on backend
cp compose-dev-backend.yml compose-private.yml
# if you mainly work on frontend
cp compose-dev-frontend.yml compose-private.yml
# now, edit / debug `compose-private.yml` to your heart's content
# build and run
docker-compose -f compose-private.yml build
docker-compose -f compose-private.yml up
```
It starts Remark42 on `127.0.0.1:8080` and adds local OAuth2 provider "Dev". To access the UI demo page go to `127.0.0.1:8080/web`. By default, you would be logged in as `dev_user` which is defined as admin. You can tweak any of [supported parameters](#parameters) in corresponded yml file.
Backend Docker Compose config by default skips running frontend related tests. Frontend Docker Compose config by default skips running backend related tests and sets `NODE_ENV=development` for frontend build.
### Backend development
To run backend locally (development mode, without Docker) you have to have the latest stable `go` toolchain [installed](https://golang.org/doc/install).
To run backend - `cd backend; go run app/main.go server --dbg --secret=12345 --url=http://127.0.0.1:8080 --admin-passwd=password --site=remark`. It stars backend service with embedded bolt store on port `8080` with basic auth, allowing to authenticate and run requests directly, like this:
`HTTP http://admin:password@127.0.0.1:8080/api/v1/find?site=remark&sort=-active&format=tree&url=http://127.0.0.1:8080`
### Frontend development
#### Developer guide
Frontend guide can be found here: [./frontend/README.md](./frontend/README.md).
#### Build
You should have at least 2GB RAM or swap enabled for building.
* install [Node.js 12.11](https://nodejs.org/en/) or higher
* install [NPM 6.13.4](https://www.npmjs.com/package/npm)
* run `npm install` inside `./frontend`
* run `npm run build` there
* result files will be saved in `./frontend/public`
**Note:** Running `npm install` will set up pre-commit hooks into your git repository. It used to reformat your frontend code using `prettier` and lint with `eslint` and `stylelint` before every commit.
#### Devserver
For local development mode with Hot Reloading use `npm start` instead of `npm run build`. In this case, `webpack` will serve files using `webpack-dev-server` on `localhost:9000`. By visiting `127.0.0.1:9000/web` you will get a page with the main comments widget communicating with a demo server backend running on `https://demo.remark42.com`. But you will not be able to log in with any OAuth providers due to security reasons.
You can attach to the locally running backend by providing `REMARK_URL` environment variable.
```shell
npx cross-env REMARK_URL=http://127.0.0.1:8080 npm start
```
**Note:** If you want to redefine env variables such as `PORT` on your local instance you can add `.env` file to `./frontend` folder and rewrite variables as you wish. For such functional, we use `dotenv`.
The best way to start a local developer environment:
```shell
cp compose-dev-frontend.yml compose-private-frontend.yml
docker-compose -f compose-private-frontend.yml up --build
cd frontend
npm run dev
```
Developer build running by `webpack-dev-server` supports devtools for [React](https://github.com/facebook/react-devtools) and
[Redux](https://github.com/zalmoxisus/redux-devtools-extension).
## Privacy
* Remark42 is trying to be very sensitive to any private or semi-private information.
site/src/docs/backup/migration/index.md
+13 -4
View File
@@ -2,21 +2,30 @@
title: Migration
---
Remark42 supports importing comments from Disqus, WordPress, or native backup format. All imported comments have an `Imported` field set to `true`.
Remark42 supports importing comments from Disqus, WordPress, Commento, or native backup format. All imported comments have an `Imported` field set to `true`. All methods below remove existing comments from they site if they are present, please use the last paragraph to preserve them.
### Import from Disqus
### Initial import from Disqus
1. Disqus provides an export of all comments on your site in a gzipped file. This option is available in your Moderation panel at Disqus Admin > Setup > Export. The export will be sent into a queue and then emailed to the address associated with your account once it's ready. Direct link to export will be something like `https://<siteud>.disqus.com/admin/discussions/export/`. See [importing-exporting](https://help.disqus.com/en/articles/1717199-importing-exporting) for more details
2. Move this file to your Remark42 host within `./var` and extract, i.e. `gunzip <disqus-export-name>.xml.gz`
3. Run import command - `docker exec -it remark42 import -p disqus -f /srv/var/{disqus-export-name}.xml -s {your site ID}`
### Import from WordPress
### Initial import from WordPress
1. Use [that instruction](https://wordpress.com/support/export/) to export comments to file using standard WordPress functionality
2. Move this file to your Remark42 host within `./var`
3. Run import command - `docker exec -it remark42 import -p wordpress -f /srv/var/{wordpress-export-name}.xml -s {your site ID}`
### Import from Commento
### Initial import from Commento
1. Move exported json file to your Remark42 host within `./var`
2. Run import command - `docker exec -it remark42 import -p commento -f /srv/var/{commento-export-name}.json -s {your site ID}`
### Import without removing existing comments
All methods above nuke the existing comments on the site. To preserve it you should make two backup files, one for the current remark42 content, and another for imported WP/Discuss/Commento content. The format of backups is straightforward json with EOL (json line) and can be easily constructed from multiple sources. Merge them together and restore them from the resulting file:
```shell
cat wp-export.json | grep -v '{"version":1' >> combined-export.json
docker exec -it remark42 restore -f combined-export.json -s {your site ID}
```
site/src/docs/configuration/authorization/index.md
+9 -8
View File
@@ -12,7 +12,7 @@ Authentication handled by external providers. You should setup OAuth2 for all (o
2. Create a new app with [this manual](https://developers.facebook.com/docs/development/create-an-app/) or use existing app
3. Open your app and choose **"Facebook Login"** and then **"Web"**
4. Set **"Site URL"** to your domain, e.g.: `https://remark42.mysite.com`
5. Under **"Facebook login" / "Settings"** fill "Valid OAuth redirect URIs" with your callback URL constructed as domain plus `/auth/facebook/callback`, e.g `https://remark42.mysite.com/auth/facebook/callback`
5. Under **"Facebook login"**/**"Settings"** fill "Valid OAuth redirect URIs" with your callback URL constructed as domain plus `/auth/facebook/callback`, e.g `https://remark42.mysite.com/auth/facebook/callback`
6. Select **"App Review"** and turn public flag on. This step may ask you to provide a link to your privacy policy
### GitHub
@@ -73,20 +73,21 @@ _instructions for Google OAuth2 setup borrowed from [oauth2_proxy](https://githu
For more details refer to [Yandex OAuth](https://yandex.com/dev/oauth/doc/dg/concepts/about.html) and [Yandex.Passport](https://yandex.com/dev/passport/doc/dg/index.html) API documentation.
### Patreon Auth provider
### Patreon
1. Create a new Patreon client https://www.patreon.com/portal/registration/register-clients
2. Fill **App Name**, **Description**
3. In the field **Redirect URIs** enter the correct URI constructed as domain + `/auth/patreon/callback`, i.e. `https://example.mysite.com/auth/patreon/callback`
4. Expand client details, take a note of the **Client ID** and **Client Secret**. Those will be used as `AUTH_PATREON_CID` and `AUTH_PATREON_CSEC`
## Anonymous Auth Provider
### Telegram
1. Contact [@BotFather](https://t.me/botfather) and follow his instructions to create your own bot (call it, for example, "My site auth bot")
1. Write down resulting token as `TELEGRAM_TOKEN` into remark42 config, and also set `AUTH_TELEGRAM` to `true` to enable telegram auth for your users.
### Anonymous
Optionally, anonymous access can be turned on. In this case, an extra `anonymous` provider will allow logins without any social login with any name satisfying 2 conditions:
- name should be at least 3 characters long
- name has to start from the letter and contains letters, numbers, underscores and spaces only
## Telegram Auth Provider
1. Contact [@BotFather](https://t.me/botfather) and follow his instructions to create your own bot (call it, for example, "My site auth bot")
1. Write down resulting token as `TELEGRAM_TOKEN` into remark42 config, and also set `AUTH_TELEGRAM` to `true` to enable telegram auth for your users.
site/src/docs/configuration/frontend/index.md
+33 -45
View File
@@ -14,55 +14,43 @@ Add this snippet to the bottom of web page:
host: 'REMARK_URL', // hostname of Remark42 server, same as REMARK_URL in backend config, e.g. "https://demo.remark42.com"
site_id: 'YOUR_SITE_ID',
components: ['embed'], // optional param; which components to load. default to ["embed"]
// to load all components define components as ['embed', 'last-comments', 'counter']
// available component are:
// - 'embed': basic comments widget
// - 'last-comments': last comments widget, see `Last Comments` section below
// - 'counter': counter widget, see `Counter` section below
// to load all components define components as ['embed', 'last-comments', 'counter']
// available component are:
// - 'embed': basic comments widget
// - 'last-comments': last comments widget, see `Last Comments` section below
// - 'counter': counter widget, see `Counter` section below
url: 'PAGE_URL', // optional param; if it isn't defined
// `window.location.origin + window.location.pathname` will be used
//
// Note that if you use query parameters as significant part of URL
// (the one that actually changes content on page)
// you will have to configure URL manually to keep query params, as
// `window.location.origin + window.location.pathname` doesn't contain query params and
// hash. For example, default URL for `https://example/com/example-post?id=1#hash`
// would be `https://example/com/example-post`
//
// The problem with query params is that they often contain useless params added by
// various trackers (utm params) and doesn't have defined order, so Remark42 treats differently
// all this examples:
// https://example.com/?postid=1&date=2007-02-11
// https://example.com/?date=2007-02-11&postid=1
// https://example.com/?date=2007-02-11&postid=1&utm_source=google
//
// If you deal with query parameters make sure you pass only significant part of it
// in well defined order
// `window.location.origin + window.location.pathname` will be used
//
// Note that if you use query parameters as significant part of URL
// (the one that actually changes content on page)
// you will have to configure URL manually to keep query params, as
// `window.location.origin + window.location.pathname` doesn't contain query params and
// hash. For example, default URL for `https://example/com/example-post?id=1#hash`
// would be `https://example/com/example-post`
//
// The problem with query params is that they often contain useless params added by
// various trackers (utm params) and doesn't have defined order, so Remark42 treats differently
// all this examples:
// https://example.com/?postid=1&date=2007-02-11
// https://example.com/?date=2007-02-11&postid=1
// https://example.com/?date=2007-02-11&postid=1&utm_source=google
//
// If you deal with query parameters make sure you pass only significant part of it
// in well defined order
max_shown_comments: 10, // optional param; if it isn't defined default value (15) will be used
theme: 'dark', // optional param; if it isn't defined default value ('light') will be used
page_title: 'Moving to Remark42', // optional param; if it isn't defined `document.title` will be used
locale: 'en', // set up locale and language, if it isn't defined default value ('en') will be used
show_email_subscription: false, // optional param; by default it is `true` and you can see email subscription feature
// in interface when enable it from backend side
// if you set this param in `false` you will get notifications email notifications as admin
// but your users won't have interface for subscription
// in interface when enable it from backend side
// if you set this param in `false` you will get notifications email notifications as admin
// but your users won't have interface for subscription
simple_view: false, // optional param; overrides the parameter from the backend
// minimized UI with basic info only
}
</script>
<script>
!(function (e, n) {
for (var o = 0; o < e.length; o++) {
var r = n.createElement('script'),
c = '.js',
d = n.head || n.body
'noModule' in r ? ((r.type = 'module'), (c = '.mjs')) : (r.async = !0),
(r.defer = !0),
(r.src = remark_config.host + '/web/' + e[o] + c),
d.appendChild(r)
}
})(remark_config.components || ['embed'], document)
// minimized UI with basic info only
};
</script>
<script>!function(e,n){for(var o=0;o<e.length;o++){var r=n.createElement("script"),c=".js",d=n.head||n.body;"noModule"in r?(r.type="module",c=".mjs"):r.async=!0,r.defer=!0,r.src=remark_config.host+"/web/"+e[o]+c,d.appendChild(r)}}(remark_config.components||["embed"],document);</script>
```
And then add this node in the place where you want to see Remark42 widget:
@@ -80,12 +68,12 @@ If you want to set this up on a Single Page App, see [appropriate doc page](site
Right now Remark42 has two themes: light and dark. You can pick one using a configuration object, but there is also a possibility to switch between themes in runtime. For this purpose Remark42 adds to `window` object named `REMARK42`, which contains a function `changeTheme`. Just call this function and pass a name of the theme that you want to turn on:
```js
window.REMARK42.changeTheme('light')
window.REMARK42.changeTheme('light');
```
##### Locales
Right now Remark42 is translated to English (en), Belarusian (be), Brazilian Portuguese (bp), Bulgarian (bg), Chinese (zh), Finnish (fi), French (fr), German (de), Japanese (ja), Korean (ko), Polish (pl), Russian (ru), Spanish (es), Turkish (tr), Ukrainian (ua) and Vietnamese (vi) languages. You can pick one using [configuration object](#setup-on-your-website).
Right now Remark42 is translated to English (en), Belarusian (be), Brazilian Portuguese (bp), Bulgarian (bg), Chinese (zh), Finnish (fi), French (fr), German (de), Japanese (ja), Korean (ko), Polish (pl), Russian (ru), Spanish (es), Turkish (tr), Ukrainian (ua), Italian (it) and Vietnamese (vi) languages. You can pick one using [configuration object](https://remark42.com/docs/getting-started/installation/#setup-on-your-website).
Do you want to translate Remark42 to other locales? Please see [this documentation](site/src/docs/contributing/translations/index.md) for details.
@@ -101,7 +89,7 @@ Add this snippet to the bottom of web page, or adjust already present `remark_co
host: 'REMARK_URL', // hostname of Remark42 server, same as REMARK_URL in backend config, e.g. "https://demo.remark42.com"
site_id: 'YOUR_SITE_ID',
components: ['last-comments'],
}
};
</script>
```
@@ -125,7 +113,7 @@ Add this snippet to the bottom of web page, or adjust already present `remark_co
host: 'REMARK_URL', // hostname of Remark42 server, same as REMARK_URL in backend config, e.g. "https://demo.remark42.com"
site_id: 'YOUR_SITE_ID',
components: ['counter'],
}
};
</script>
```
site/src/docs/contributing/development/index.md
+1 -1
View File
@@ -34,7 +34,7 @@ To run backend - `cd backend; go run app/main.go server --dbg --secret=12345 --u
#### Developer guide
Frontend guide can be found here: [./frontend/README.md](./frontend/README.md).
Brief frontend guide can be found [here](https://github.com/umputun/remark42/tree/master/frontend#readme).
#### Build
site/src/docs/getting-started/installation/index.md
+3 -3
View File
@@ -6,16 +6,16 @@ title: Installation
### Installation in Docker
_This is the recommended way to run remark42_
_This is the recommended way to run Remark42_
- copy provided `docker-compose.yml` and customize for your needs
- make sure you **don't keep** `ADMIN_PASSWD=something...` for any non-development deployments
- pull prepared images from the DockerHub and start - `docker-compose pull && docker-compose up -d`
- pull prepared images from the Docker Hub and start - `docker-compose pull && docker-compose up -d`
- alternatively compile from the sources - `docker-compose build && docker-compose up -d`
### Installation with Binary
- download archive for [stable release](https://github.com/umputun/remark42/releases) or [development version](https://remark42.com/downloads)
- download [archive for stable release](https://github.com/umputun/remark42/releases)
- unpack with `gunzip` (Linux, macOS) or with `zip` (Windows)
- run as `remark42.{os}-{arch} server {parameters...}`, i.e. `remark42.linux-amd64 server --secret=12345 --url=http://127.0.0.1:8080`
- alternatively compile from the sources - `make OS=[linux|darwin|windows] ARCH=[amd64,386,arm64,arm]`