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

Improve frontend docs

Browse Source
This commit is contained in:
Paul Mineev
2022-04-10 11:18:15 -05:00
committed by Umputun
parent d89c9a1d1c
commit f7bddd757d
4 changed files with 144 additions and 133 deletions
Download Patch File Download Diff File Expand all files Collapse all files
site/src/docs/configuration/frontend/index.md
+64 -128
View File
@@ -2,68 +2,69 @@
title: Frontend Configuration
---
## Comments
## Configuration
It's the main widget that renders a list of comments.
- **`host`**`: string` (required) – hostname of Remark42 server, same as REMARK_URL in backend config, e.g. "https://demo.remark42.com"
- **`site_id`**`: string` (optional, `remark` by default) – the `SITE` that you passed to Remark42 instance on start of backend.
- **`url`**`: string` (optional, `window.location.origin + window.location.pathname` by default) – url to the page with comments, it is used as unique identificator for comments thread
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`
- **`components`**`: ['embed' | 'last-comments' | 'counter']` (optional, `['embed']` by default) – an array of widgets that should be rendered on a page. You may use more than one widget on a page.
Available components are:
- `'embed'` – basic comments widget
- `'last-comments'` – last comments widget, see [Last Comments](#last-comments-widget) section below
- `'counter'` – counter widget, see [Counter](#counter-widget) section below
- **`max_shown_comments`**`: number` (optional, `15` by default) – maximum number of comments that is renered on mobile version
- **`theme`**`: 'light' | 'dark'` (optional, `'light'` by default) – changes UI theme
- **`page_title`**`: string` (optional, `document.title` by default) – title for current comments page
- **`locale`**`: enum` (optional, `'en'` by default) – interface localization, [check possible localizations](#locales)
- **`show_email_subscription`**`: boolean` (optional, `true` by default) – enables 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`**`: boolean` (optional, `false` by default) – overrides the parameter from the backend minimized UI with basic info only
Add this snippet to the bottom of web page:
Example with all of the params:
```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
};
host: 'https://remark42.example.com',
site_id: 'my_site',
components: ['embeded', 'last-comments']
max_shown_comments: 100,
theme: 'dark',
page_title: 'My custom title for a page',
locale: 'es',
show_email_subscription: false,
simple_view: true
}
</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:
## Basic configuration
Place configuration on a page of your site.
Add following **initialization** script after it.
<!-- prettier-ignore-start -->
```html
<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>
```
<!-- prettier-ignore-end -->
## Comments
It's the main widget that renders a list of comments with ability of commenting.
Add following snippet in the place where you want to see Remark42 widget. The comments widget will be rendered in that place.
```html
<div id="remark42"></div>
```
::: note 💡
**Note:** The initialization script should be placed after the code mentioned above.
:::
After that widget will be rendered inside this node.
If you want to set this up on a Single Page App, see the [appropriate doc page](https://remark42.com/docs/configuration/frontend/spa/).
If you want to set this up on a Single Page App, see the [appropriate doc page](https://remark42.com/docs/configuration/frontend/).
##### Themes
#### Themes
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 the `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:
@@ -71,13 +72,15 @@ Remark42 has two themes: light and dark. You can pick one using a configuration
window.REMARK42.changeTheme('light');
```
##### Locales
#### 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 a [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](https://remark42.com/docs/contributing/translations/) for details.
#### Last comments
## Widgets
### Last comments widget
It's a widget that renders the list of last comments from your site.
@@ -86,13 +89,17 @@ Add this snippet to the bottom of web page, or adjust already present `remark_co
```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"
host: 'REMARK_URL',
site_id: 'YOUR_SITE_ID',
components: ['embed', 'last-comments'],
components: ['last-comments'],
};
</script>
```
::: note 💡
**Note:** If you want to render not only last comments widget you need to add all of the names of widget that you want to initialize.
:::
And then add this node in the place where you want to see last comments widget:
```html
@@ -101,22 +108,25 @@ And then add this node in the place where you want to see last comments widget:
`data-max` sets the max amount of comments (default: `15`).
#### Counter
### Counter widget
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"
host: 'REMARK_URL',
site_id: 'YOUR_SITE_ID',
components: ['embed', 'counter'],
components: ['counter'],
};
</script>
```
::: note 💡
**Note:** If you want to render not only comments widget you need to add all of the names of widget that you want to initialize.
:::
And then add a node like this in the place where you want to see a number of comments:
```html
@@ -130,77 +140,3 @@ You can use as many nodes like this as you need to. The script will find all of
Also, the script can use `url` property from `remark_config` object or `window.location.origin + window.location.pathname` if nothing else is defined.
## Widgets
### Counter widget
### Last comments widget
## API for Single-Page Applications
Tested initially on [Nuxt.js](https://nuxtjs.org/), but it should apply to all SPAs.
- Add the following JavaScript to your `index.html`, which in this case, it is identical to `<script defer src="$HOST/web/embed.js"></script>`
```js
;(function () {
var host = // Your remark42 host
var components = ['embed'] // Your choice of remark42 components
;(function(c) {
for (let i = 0; i < c.length; i++) {
const d = document
const s = d.createElement('script')
s.src = remark_config.host + '/web/' + c[i] + '.js'
s.defer = true
;(d.head || d.body).appendChild(s)
}
})(components)
})
```
- Created `remark42Instance` when the `div` containing remark42 has appeared, usually at `mounted` or `componentDidMount` of the SPA lifecycle. Destroy the previous instance first, if necessary.
```ts
initRemark42() {
if (window.REMARK42) {
if (this.remark42Instance) {
this.remark42Instance.destroy()
}
this.remark42Instance = window.REMARK42.createInstance({
node: this.$refs.remark42 as HTMLElement,
...remark42_config // See <https://github.com/patarapolw/remark42#setup-on-your-website>
})
}
}
mounted() {
if (window.REMARK42) {
this.initRemark42()
} else {
window.addEventListener('REMARK42::ready', () => {
this.initRemark42()
})
}
}
```
- Ensure that this is called every time route changes
```ts
@Watch('$route.path')
onRouteChange() {
this.initRemark42()
}
```
- And, destroyed before routeLeave
```ts
beforeRouteLeave() {
if (this.remark42Instance) {
this.remark42Instance.destroy()
}
}
```
site/src/docs/configuration/frontend/spa.md
+67
View File
@@ -0,0 +1,67 @@
## API for Single-Page Application
Add the following JavaScript to your `index.html`, which in this case, it is identical to `<script defer src="$HOST/web/embed.js"></script>`
```js
;(function () {
var host = // Your remark42 host
var components = ['embed'] // Your choice of remark42 components
;(function(c) {
for (let i = 0; i < c.length; i++) {
const d = document
const s = d.createElement('script')
s.src = remark_config.host + '/web/' + c[i] + '.js'
s.defer = true
;(d.head || d.body).appendChild(s)
}
})(components)
})
```
Created `remark42Instance` when the `div` containing remark42 has appeared, usually at `mounted` or `componentDidMount` of the SPA lifecycle. Destroy the previous instance first, if necessary.
```ts
initRemark42() {
if (window.REMARK42) {
if (this.remark42Instance) {
this.remark42Instance.destroy()
}
this.remark42Instance = window.REMARK42.createInstance({
node: this.$refs.remark42 as HTMLElement,
...remark42_config // See <https://github.com/patarapolw/remark42#setup-on-your-website>
})
}
}
mounted() {
if (window.REMARK42) {
this.initRemark42()
} else {
window.addEventListener('REMARK42::ready', () => {
this.initRemark42()
})
}
}
```
- Ensure that this is called every time route changes
```ts
@Watch('$route.path')
onRouteChange() {
this.initRemark42()
}
```
- And, destroyed before routeLeave
```ts
beforeRouteLeave() {
if (this.remark42Instance) {
this.remark42Instance.destroy()
}
}
```
site/src/docs/getting-started/installation/index.md
+6 -5
View File
@@ -24,6 +24,9 @@ _This is the recommended way to run Remark42_
Add config for Remark on a page of your site ([here](/docs/configuration/frontend/) is the full reference):
- `REMARK_URL` – the URL where is Remark42 instance is served, passed as `REMARK_URL` to backend
- `YOUR_SITE_ID` - the `SITE` that you passed to Remark42 instance on start, `remark` by default.
```html
<script>
var remark_config = {
@@ -33,9 +36,6 @@ Add config for Remark on a page of your site ([here](/docs/configuration/fronten
</script>
```
- `REMARK_URL` – the URL where is Remark42 instance is served, passed as `REMARK_URL` to backend
- `YOUR_SITE_ID` - the `SITE` that you passed to Remark42 instance on start, `remark` by default.
For example:
```html
@@ -56,7 +56,7 @@ After that place the code snippet right after config.
<!-- prettier-ignore-end -->
::: note 💡
**Note that:** You can place the config with the snippet in any place of the HTML code of your site. If it is closer to start of the HTML (for example in `<head>`) it will start loading sooner and show comments faster.
**Note:** You can place the config with the snippet in any place of the HTML code of your site. If it is closer to start of the HTML (for example in `<head>`) it will start loading sooner and show comments faster.
:::
Put the next code snippet on a page of your site where you want to have comments:
@@ -67,7 +67,8 @@ Put the next code snippet on a page of your site where you want to have comments
After that widget will be rendered inside this node.
If you want to set this up on a Single Page App, see the [appropriate doc page](https://remark42.com/docs/configuration/frontend/).
For more information about frontend configuration please [learn about other parameters here](https://remark42.com/docs/configuration/frontend/)
If you want to set this up on a Single Page App, see the [appropriate doc page](https://remark42.com/docs/configuration/frontend/spa/).
#### Quick installation test
site/src/styles.css
+7
View File
@@ -2,6 +2,13 @@
@tailwind components;
@tailwind utilities;
.prose code {
@apply before:hidden after:hidden text-brand-800 dark:text-brand-300 font-light;
}
.prose strong code {
@apply font-bold text-yellow-600 dark:text-yellow-400;;
}
.burger-icon {
@apply relative inline-block w-4 h-4 mr-3;
}