Update docs

3 files changed, 70 insertions, 5 deletions

diff --git a/docs/_sidebar.md b/docs/_sidebar.md
index aeaf50a..8af9cdd 100644
--- a/docs/_sidebar.md
+++ b/docs/_sidebar.md
@@ -10,7 +10,8 @@
 - [Dark Mode](dark-mode.md)
 - [Highlight.js](highlightjs.md)
 - [Search](search.md)
-- [Custom Archives Header](custom-archives-header.md)
+- [Custom archives header](custom-archives-header.md)
 - [Summary Images](summary-images.md)
 - [Post as Image](post-as-image.md)
 - [Netlify CMS](netlify-cms.md)
+- [Custom theme](custom.md)
diff --git a/docs/custom-archives-header.md b/docs/custom-archives-header.md
index edc1ab4..64b5554 100644
--- a/docs/custom-archives-header.md
+++ b/docs/custom-archives-header.md
@@ -1,8 +1,6 @@
-# Custom Archives Header
+# Custom archives header
 
-You can custom you `/posts` page's header with a `_index.md`.
-
-Place the `_index.md` in `content/posts`.
+You can custom your `/posts` page's header by placing a `_index.md` in `content/posts`.
 
 For example, paste below in `_index.md`:
 
diff --git a/docs/custom.md b/docs/custom.md
new file mode 100644
index 0000000..d957cad
--- /dev/null
+++ b/docs/custom.md
@@ -0,0 +1,66 @@
+# Custom theme
+
+This doc describes how to add `CSS` and `JS` to customize the theme within a certain range.
+
+Before customization, you need to add the related fields to your configuration, below is an example:
+
+```toml
+[params]
+  [params.advanced]
+    customCSS = ["css/custom.css"] # files in the list will be loaded in order
+    customJS = ["js/custom.js"]
+```
+
+## CSS
+
+It’s very easy to change the theme through CSS. Dream theme base on [Semantic UI](https://semantic-ui.com/), and nearly all the custom classes start with the `dream-` prefix. So in most cases, you only need to customize in these two ways:
+
+- **Override Semantic UI classes**
+- **Override Dream specified classes** (Can be found in [site.scss](https://github.com/g1eny0ung/hugo-theme-dream/blob/master/src/sass/site.scss))
+
+Here are some examples:
+
+### Dim background in dark mode
+
+This CSS snippet is useful when you want the `backgroundImage` and `backgroundImageDark` params to be the same and adapt to dark mode.
+
+```css
+body.dark .os-viewport {
+  background-color: rgba(0, 0, 0, 0.6);
+}
+```
+
+### Change dark mode color
+
+Due to the Dream theme use Semantic UI `.ui.inverted` as the color of dark mode, so you can change it by:
+
+```css
+.ui.inverted.segment,
+#dream-search.inverted .results {
+  background-color: #333;
+}
+```
+
+### Custom masonry layouts' item
+
+```css
+.ui.attached.segment.dream-card {
+  border: none;
+  border-radius: 1.5em;
+  box-shadow: 0 0.5em 1em -0.125em rgb(10 10 10 / 10%), 0 0 0 1px rgb(10 10 10 / 2%); /* Bulma Box */
+}
+```
+
+### Custom TOC
+
+```css
+.ui.segment.toc {
+  padding: 0;
+  background: none;
+  border: none;
+  box-shadow: none;
+  float: right;
+}
+```
+
+## JS