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

fix files naming add files to menu

Browse Source
This commit is contained in:
Pavel Mineev
2020-10-11 17:12:14 -05:00
committed by Umputun
parent fc9882098d
commit 7b1ecccb4b
15 changed files with 210 additions and 156 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/1.6/_index.md
+7
View File
@@ -0,0 +1,7 @@
# Documentation and FAQ
- [How to configure remark42 with nginx reverse proxy](nginx-proxy)
- [How to configure remark42 without a subdomain](subdomain) with Nginx or Caddy
- [Telegram notifications](telegram)
- [Setup email authentication and\or email notifications](email)
- [How to add new translation to remark42](translation)
docs/1.6/email.md
+34 -28
View File
@@ -1,18 +1,22 @@
---
title: Email
---
## Overview
This documentation describes how to enable the email-related capabilities of Remark.
- email authentication for users:
enabling this will let the user log in using their emails:
enabling this will let the user log in using their emails:
![Email authentication](/docs/images/email_auth.png?raw=true)
![Email authentication](/docs/images/email_auth.png?raw=true)
- email notifications for any users except anonymous:
GitHub or Google or Twitter or any other kind of user gets the ability to get email notifications about new replies to their comments:
GitHub or Google or Twitter or any other kind of user gets the ability to get email notifications about new replies to their comments:
![Email notifications subscription](/docs/images/email_notifications.png?raw=true)
![Email notifications subscription](/docs/images/email_notifications.png?raw=true)
## Setup email server connection
@@ -58,21 +62,22 @@ To use any of containers below with in remark42 environment set following two `S
Here is `docker-compose.yml` configuration part spinning up a container for
[stevenolen/mailgun-smtp-server](https://hub.docker.com/r/stevenolen/mailgun-smtp-server):
```yaml
mailgun:
image: stevenolen/mailgun-smtp-server
container_name: "mail"
hostname: "mail"
mailgun:
image: stevenolen/mailgun-smtp-server
container_name: 'mail'
hostname: 'mail'
logging:
driver: json-file
options:
max-size: "10m"
max-file: "5"
logging:
driver: json-file
options:
max-size: '10m'
max-file: '5'
environment:
- MG_KEY=key-123456789
- MG_DOMAIN=example.com
environment:
- MG_KEY=key-123456789
- MG_DOMAIN=example.com
```
Please note that before
@@ -110,20 +115,21 @@ To use any of containers below with in remark42 environment set following two `S
Here is `docker-compose.yml` configuration part spinning up a container for
[fgribreau/smtp-to-sendgrid-gateway](https://hub.docker.com/r/fgribreau/smtp-to-sendgrid-gateway):
```yaml
sendgrid:
image: fgribreau/smtp-to-sendgrid-gateway
container_name: "mail"
hostname: "mail"
sendgrid:
image: fgribreau/smtp-to-sendgrid-gateway
container_name: 'mail'
hostname: 'mail'
logging:
driver: json-file
options:
max-size: "10m"
max-file: "5"
logging:
driver: json-file
options:
max-size: '10m'
max-file: '5'
environment:
- SENDGRID_API=key-123456789
environment:
- SENDGRID_API=key-123456789
```
### Gmail
@@ -143,6 +149,7 @@ Configuration example for Gmail:
### Amazon SES
Configuration example for [Amazon SES](https://aws.amazon.com/ses/) (us-east-1 region):
```yaml
- SMTP_HOST=email-smtp.us-east-1.amazonaws.com
- SMTP_PORT=465
@@ -176,7 +183,6 @@ After you set `SMTP_` variables, you can allow email authentication by setting t
- AUTH_EMAIL_FROM=notify@example.com
```
Usually, you don't need to change/set anything else. In case if you want to use a different email template set `AUTH_EMAIL_TEMPLATE`, for instance
`- AUTH_EMAIL_TEMPLATE="Confirmation email, token: {{.Token}}"`. See [verified-authentication](https://github.com/go-pkgz/auth#verified-authentication) for more details.
docs/1.6/index.md
-7
View File
@@ -1,7 +0,0 @@
# Documentation and FAQ
- [How to configure remark42 with nginx reverse proxy](nginx-proxy.md)
- [How to configure remark42 without a subdomain](subdomain.md) with Nginx or Caddy
- [Telegram notifications](telegram.md)
- [Setup email authentication and\or email notifications](email.md)
- [How to add new translation to remark42](translation.md)
docs/1.6/nginx-proxy.md
+5 -1
View File
@@ -1,3 +1,7 @@
---
title: Nginx
---
## How to configure remark42 with nginx reverse proxy
Example of nginx configuration (reverse proxy) running remark42 service on remark42.example.com
@@ -47,4 +51,4 @@ server {
}
```
note: `proxy_pass` points to internal DNS name `remark42` and expected to run from the same compose. If nginx runs outside of compose the real IP (or docker's bridge IP) should be used
note: `proxy_pass` points to internal DNS name `remark42` and expected to run from the same compose. If nginx runs outside of compose the real IP (or docker's bridge IP) should be used
docs/1.6/subdomain.md
+14 -10
View File
@@ -1,6 +1,10 @@
---
title: Subdomain
---
## How to configure remark42 without a subdomain
All README examples show configurations with remark42 on its own subdomain, i.e. `https://remark42.example.com`. However, it is possible and sometimes desirable to run remark42 without a subdomain, but just under some path, i.e. `https://example.com/remark42`.
All README examples show configurations with remark42 on its own subdomain, i.e. `https://remark42.example.com`. However, it is possible and sometimes desirable to run remark42 without a subdomain, but just under some path, i.e. `https://example.com/remark42`.
- The frontend URL looks like this: `s.src = 'https://example.com/remark42/web/embed.js;`
@@ -25,16 +29,16 @@ services:
container_name: remark42
restart: always
environment:
- REMARK_URL=https://example.com/remark42/
- SITE=<site_ID>
- SECRET=<secret>
- ADMIN_SHARED_ID=<shared_id>
- REMARK_URL=https://example.com/remark42/
- SITE=<site_ID>
- SECRET=<secret>
- ADMIN_SHARED_ID=<shared_id>
volumes:
- ./data:/srv/var
- ./data:/srv/var
logging:
options:
max-size: "10m"
max-file: "1"
options:
max-size: '10m'
max-file: '1'
```
### Nginx configuration
@@ -67,7 +71,7 @@ example.com {
# remark42
proxy /remark42/ http://remark42:8080/ {
without /remark42
transparent
transparent
}
}
```
docs/1.6/telegram.md
+6 -2
View File
@@ -1,8 +1,12 @@
---
title: Telegram
---
## Telegram notifications
In order to integrate notifications from remark42 with the [telegram](https://telegram.org), you should make [a channel](https://telegram.org/faq_channels) and obtain a token. This token should be used as `NOTIFY_TELEGRAM_TOKEN`. You also need to set `NOTIFY_TYPE=telegram` and set `NOTIFY_TELEGRAM_CHAN` to your channel.
In order to integrate notifications from remark42 with the [telegram](https://telegram.org), you should make [a channel](https://telegram.org/faq_channels) and obtain a token. This token should be used as `NOTIFY_TELEGRAM_TOKEN`. You also need to set `NOTIFY_TYPE=telegram` and set `NOTIFY_TELEGRAM_CHAN` to your channel.
In order to get token "just talk to [BotFather](https://core.telegram.org/bots#6-botfather)". All you need is to send `/newbot` command, choose bot name and the name for your bot (it must end in `bot`). This is it, you got a token.
In order to get token "just talk to [BotFather](https://core.telegram.org/bots#6-botfather)". All you need is to send `/newbot` command, choose bot name and the name for your bot (it must end in `bot`). This is it, you got a token.
_Example of such a "talk":_
docs/1.6/translation.md
+36 -29
View File
@@ -1,3 +1,7 @@
---
title: Translation
---
## How to add new language translation to Remark42
Translation files are stored in [/frontend/app/locales](https://github.com/umputun/remark42/tree/master/frontend/app/locales)
@@ -17,33 +21,36 @@ directory with `.json` extension and content like following:
We truly appreciate people spending time contributing their translations to remark42. Please go through the steps
below in order to have your translation start being available to all remark42 users and included in the next release.
1. create a fork of [umputun/remark42](https://github.com/umputun/remark42) repo, and if you already have one please
pull the latest changes from the upstream master branch. It could be done like that:
```shell
git remote add upstream https://github.com/umputun/remark42.git
git fetch upstream
git rebase upstream/master
git push
```
1. add new locale with [two-letter code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes)
of the language you want to make the translation into to list in
[frontend/tasks/supportedLocales.json](https://github.com/umputun/remark42/blob/master/frontend/tasks/supportedLocales.json)
1. run `npm run translation:generate` in `frontend` folder
1. translate all values in the newly created json file in
[frontend/app/locales/](https://github.com/umputun/remark42/blob/master/frontend/app/locales/)
1. commit all changes above in your fork
1. test your changes in the interface:
1. uncomment `locale: "ru"` line in [frontend/index.ejs](https://github.com/umputun/remark42/blob/master/frontend/index.ejs#L133)
and replace `ru` with your translation language code
1. [run remark42 in Docker](https://github.com/umputun/remark42#development) by issuing following commands
from the root directory of your remark42 fork:
1. create a fork of [umputun/remark42](https://github.com/umputun/remark42) repo, and if you already have one please
pull the latest changes from the upstream master branch. It could be done like that:
```shell
git remote add upstream https://github.com/umputun/remark42.git
git fetch upstream
git rebase upstream/master
git push
```
1. add new locale with [two-letter code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes)
of the language you want to make the translation into to list in
[frontend/tasks/supportedLocales.json](https://github.com/umputun/remark42/blob/master/frontend/tasks/supportedLocales.json)
1. run `npm run translation:generate` in `frontend` folder
1. translate all values in the newly created json file in
[frontend/app/locales/](https://github.com/umputun/remark42/blob/master/frontend/app/locales/)
1. commit all changes above in your fork
1. test your changes in the interface:
```shell
docker-compose -f compose-dev-frontend.yml build
docker-compose -f compose-dev-frontend.yml up
```
1. open [http://127.0.0.1:8080](http://127.0.0.1:8080), log in, make a comment, make a reply to a comment,
and make sure that your translation looks as you expect it to look
1. make a screenshot from [http://127.0.0.1:8080](http://127.0.0.1:8080) with your translation in place
1. after all previous steps are done, create a [Pull Request](https://github.com/umputun/remark42/pulls) to umputun/remark42
repo with your changes, attaching a screenshot or two from your local test instance to it
1. uncomment `locale: "ru"` line in [frontend/index.ejs](https://github.com/umputun/remark42/blob/master/frontend/index.ejs#L133)
and replace `ru` with your translation language code
1. [run remark42 in Docker](https://github.com/umputun/remark42#development) by issuing following commands
from the root directory of your remark42 fork:
```shell
docker-compose -f compose-dev-frontend.yml build
docker-compose -f compose-dev-frontend.yml up
```
1. open [http://127.0.0.1:8080](http://127.0.0.1:8080), log in, make a comment, make a reply to a comment,
and make sure that your translation looks as you expect it to look
1. make a screenshot from [http://127.0.0.1:8080](http://127.0.0.1:8080) with your translation in place
1. after all previous steps are done, create a [Pull Request](https://github.com/umputun/remark42/pulls) to umputun/remark42
repo with your changes, attaching a screenshot or two from your local test instance to it
docs/latest/_index.md
+8
View File
@@ -0,0 +1,8 @@
# Documentation and FAQ
- [How to configure remark42 with nginx reverse proxy](nginx-proxy)
- [How to configure remark42 without a subdomain](subdomain) with Nginx or Caddy
- [How to configure remark42 for Single Page Apps (SPA)](spa)
- [Telegram notifications](telegram)
- [Setup email authentication and\or email notifications](email)
- [How to add new translation to remark42](translation)
docs/latest/email.md
+34 -28
View File
@@ -1,18 +1,22 @@
---
title: Email
---
## Overview
This documentation describes how to enable the email-related capabilities of Remark.
- email authentication for users:
enabling this will let the user log in using their emails:
enabling this will let the user log in using their emails:
![Email authentication](/docs/images/email_auth.png?raw=true)
![Email authentication](/docs/images/email_auth.png?raw=true)
- email notifications for any users except anonymous:
GitHub or Google or Twitter or any other kind of user gets the ability to get email notifications about new replies to their comments:
GitHub or Google or Twitter or any other kind of user gets the ability to get email notifications about new replies to their comments:
![Email notifications subscription](/docs/images/email_notifications.png?raw=true)
![Email notifications subscription](/docs/images/email_notifications.png?raw=true)
## Setup email server connection
@@ -58,21 +62,22 @@ To use any of containers below with in remark42 environment set following two `S
Here is `docker-compose.yml` configuration part spinning up a container for
[stevenolen/mailgun-smtp-server](https://hub.docker.com/r/stevenolen/mailgun-smtp-server):
```yaml
mailgun:
image: stevenolen/mailgun-smtp-server
container_name: "mail"
hostname: "mail"
mailgun:
image: stevenolen/mailgun-smtp-server
container_name: 'mail'
hostname: 'mail'
logging:
driver: json-file
options:
max-size: "10m"
max-file: "5"
logging:
driver: json-file
options:
max-size: '10m'
max-file: '5'
environment:
- MG_KEY=key-123456789
- MG_DOMAIN=example.com
environment:
- MG_KEY=key-123456789
- MG_DOMAIN=example.com
```
Please note that before
@@ -110,20 +115,21 @@ To use any of containers below with in remark42 environment set following two `S
Here is `docker-compose.yml` configuration part spinning up a container for
[fgribreau/smtp-to-sendgrid-gateway](https://hub.docker.com/r/fgribreau/smtp-to-sendgrid-gateway):
```yaml
sendgrid:
image: fgribreau/smtp-to-sendgrid-gateway
container_name: "mail"
hostname: "mail"
sendgrid:
image: fgribreau/smtp-to-sendgrid-gateway
container_name: 'mail'
hostname: 'mail'
logging:
driver: json-file
options:
max-size: "10m"
max-file: "5"
logging:
driver: json-file
options:
max-size: '10m'
max-file: '5'
environment:
- SENDGRID_API=key-123456789
environment:
- SENDGRID_API=key-123456789
```
### Gmail
@@ -143,6 +149,7 @@ Configuration example for Gmail:
### Amazon SES
Configuration example for [Amazon SES](https://aws.amazon.com/ses/) (us-east-1 region):
```yaml
- SMTP_HOST=email-smtp.us-east-1.amazonaws.com
- SMTP_PORT=465
@@ -176,7 +183,6 @@ After you set `SMTP_` variables, you can allow email authentication by setting t
- AUTH_EMAIL_FROM=notify@example.com
```
Usually, you don't need to change/set anything else. In case if you want to use a different email template set `AUTH_EMAIL_TEMPLATE`, for instance
`- AUTH_EMAIL_TEMPLATE="Confirmation email, token: {{.Token}}"`. See [verified-authentication](https://github.com/go-pkgz/auth#verified-authentication) for more details.
docs/latest/index.md
-8
View File
@@ -1,8 +0,0 @@
# Documentation and FAQ
- [How to configure remark42 with nginx reverse proxy](nginx-proxy.md)
- [How to configure remark42 without a subdomain](subdomain.md) with Nginx or Caddy
- [How to configure remark42 for Single Page Apps (SPA)](spa.md)
- [Telegram notifications](telegram.md)
- [Setup email authentication and\or email notifications](email.md)
- [How to add new translation to remark42](translation.md)
docs/latest/nginx-proxy.md
+4
View File
@@ -1,3 +1,7 @@
---
title: Nginx
---
## How to configure remark42 with nginx reverse proxy
Example of nginx configuration (reverse proxy) running remark42 service on remark42.example.com
docs/latest/spa.md
+4
View File
@@ -1,3 +1,7 @@
---
title: SPA
---
## How to configure remark42 for Single Page Apps (SPA)
Originally tested on [Nuxt.js](https://nuxtjs.org/), but it should be applicable to all SPAs.
docs/latest/subdomain.md
+14 -10
View File
@@ -1,6 +1,10 @@
---
title: Subdomain
---
## How to configure remark42 without a subdomain
All README examples show configurations with remark42 on its own subdomain, i.e. `https://remark42.example.com`. However, it is possible and sometimes desirable to run remark42 without a subdomain, but just under some path, i.e. `https://example.com/remark42`.
All README examples show configurations with remark42 on its own subdomain, i.e. `https://remark42.example.com`. However, it is possible and sometimes desirable to run remark42 without a subdomain, but just under some path, i.e. `https://example.com/remark42`.
- The frontend URL looks like this: `s.src = 'https://example.com/remark42/web/embed.js;`
@@ -25,16 +29,16 @@ services:
container_name: remark42
restart: always
environment:
- REMARK_URL=https://example.com/remark42/
- SITE=<site_ID>
- SECRET=<secret>
- ADMIN_SHARED_ID=<shared_id>
- REMARK_URL=https://example.com/remark42/
- SITE=<site_ID>
- SECRET=<secret>
- ADMIN_SHARED_ID=<shared_id>
volumes:
- ./data:/srv/var
- ./data:/srv/var
logging:
options:
max-size: "10m"
max-file: "1"
options:
max-size: '10m'
max-file: '1'
```
### Nginx configuration
@@ -67,7 +71,7 @@ example.com {
# remark42
proxy /remark42/ http://remark42:8080/ {
without /remark42
transparent
transparent
}
}
```
docs/latest/telegram.md
+6 -2
View File
@@ -1,8 +1,12 @@
---
title: Telegram
---
## Telegram notifications
In order to integrate notifications from remark42 with the [telegram](https://telegram.org), you should make [a channel](https://telegram.org/faq_channels) and obtain a token. This token should be used as `NOTIFY_TELEGRAM_TOKEN`. You also need to set `NOTIFY_TYPE=telegram` and set `NOTIFY_TELEGRAM_CHAN` to your channel.
In order to integrate notifications from remark42 with the [telegram](https://telegram.org), you should make [a channel](https://telegram.org/faq_channels) and obtain a token. This token should be used as `NOTIFY_TELEGRAM_TOKEN`. You also need to set `NOTIFY_TYPE=telegram` and set `NOTIFY_TELEGRAM_CHAN` to your channel.
In order to get token "just talk to [BotFather](https://core.telegram.org/bots#6-botfather)". All you need is to send `/newbot` command, choose bot name and the name for your bot (it must end in `bot`). This is it, you got a token.
In order to get token "just talk to [BotFather](https://core.telegram.org/bots#6-botfather)". All you need is to send `/newbot` command, choose bot name and the name for your bot (it must end in `bot`). This is it, you got a token.
_Example of such a "talk":_
docs/latest/translation.md
+38 -31
View File
@@ -1,3 +1,7 @@
---
title: Translation
---
## How to add new language translation to Remark42
Translation files are stored in [/frontend/app/locales](https://github.com/umputun/remark42/tree/master/frontend/app/locales)
@@ -17,35 +21,38 @@ directory with `.json` extension and content like following:
We truly appreciate people spending time contributing their translations to remark42. Please go through the steps
below in order to have your translation start being available to all remark42 users and included in the next release.
1. create a fork of [umputun/remark42](https://github.com/umputun/remark42) repo, and if you already have one please
pull the latest changes from the upstream master branch. It could be done like that:
```shell
git remote add upstream https://github.com/umputun/remark42.git
git fetch upstream
git rebase upstream/master
git push
```
1. add new locale with [two-letter code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes)
of the language you want to make the translation into to list in
[frontend/tasks/supportedLocales.json](https://github.com/umputun/remark42/blob/master/frontend/tasks/supportedLocales.json)
1. run `npm install` in `frontend` folder
1. run `npm run translation:extract` in `frontend` folder
1. run `npm run translation:generate` in `frontend` folder
1. translate all values in the newly created json file in
[frontend/app/locales/](https://github.com/umputun/remark42/blob/master/frontend/app/locales/)
1. commit all changes above in your fork
1. test your changes in the interface:
1. uncomment `locale: "ru"` line in [frontend/index.ejs](https://github.com/umputun/remark42/blob/master/frontend/index.ejs#L133)
and replace `ru` with your translation language code
1. [run remark42 in Docker](https://github.com/umputun/remark42#development) by issuing following commands
from the root directory of your remark42 fork:
1. create a fork of [umputun/remark42](https://github.com/umputun/remark42) repo, and if you already have one please
pull the latest changes from the upstream master branch. It could be done like that:
```shell
git remote add upstream https://github.com/umputun/remark42.git
git fetch upstream
git rebase upstream/master
git push
```
1. add new locale with [two-letter code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes)
of the language you want to make the translation into to list in
[frontend/tasks/supportedLocales.json](https://github.com/umputun/remark42/blob/master/frontend/tasks/supportedLocales.json)
1. run `npm install` in `frontend` folder
1. run `npm run translation:extract` in `frontend` folder
1. run `npm run translation:generate` in `frontend` folder
1. translate all values in the newly created json file in
[frontend/app/locales/](https://github.com/umputun/remark42/blob/master/frontend/app/locales/)
1. commit all changes above in your fork
1. test your changes in the interface:
```shell
docker-compose -f compose-dev-frontend.yml build
docker-compose -f compose-dev-frontend.yml up
```
1. open [http://127.0.0.1:8080/web](http://127.0.0.1:8080/web), log in, make a comment, make a reply to a comment,
and make sure that your translation looks as you expect it to look
1. make a screenshot from [http://127.0.0.1:8080](http://127.0.0.1:8080) with your translation in place
1. after all previous steps are done, create a [Pull Request](https://github.com/umputun/remark42/pulls) to umputun/remark42
repo with your changes, attaching a screenshot or two from your local test instance to it
1. uncomment `locale: "ru"` line in [frontend/index.ejs](https://github.com/umputun/remark42/blob/master/frontend/index.ejs#L133)
and replace `ru` with your translation language code
1. [run remark42 in Docker](https://github.com/umputun/remark42#development) by issuing following commands
from the root directory of your remark42 fork:
```shell
docker-compose -f compose-dev-frontend.yml build
docker-compose -f compose-dev-frontend.yml up
```
1. open [http://127.0.0.1:8080/web](http://127.0.0.1:8080/web), log in, make a comment, make a reply to a comment,
and make sure that your translation looks as you expect it to look
1. make a screenshot from [http://127.0.0.1:8080](http://127.0.0.1:8080) with your translation in place
1. after all previous steps are done, create a [Pull Request](https://github.com/umputun/remark42/pulls) to umputun/remark42
repo with your changes, attaching a screenshot or two from your local test instance to it