feat(*): several new features and fixes

- config generator now can add multiple lines of comment
- sidebars can be set to sticky on tablet and desktop devices #359
- fix toc widget display issue when it's on the right sidebar #360
- update some links in the config specs

includes/common/ConfigGenerator.js

@@ -55,7 +55,10 @@ function generate(spec, parentConfig = null) {
                     defaults = {};
                 }
                 if (spec[key].hasOwnProperty(doc)) {
-                    defaults['#' + key] = spec[key][doc];
+                    let i = 0;
+                    for (let line of spec[key][doc].split('\n')) {
+                        defaults['#' + key + i++] = line;
+                    }
                 }
                 defaults[key] = value;
             }

includes/specs/article.spec.js

@@ -5,7 +5,7 @@ module.exports = {
     [doc]: 'Article display settings',
     highlight: {
         [type]: 'string',
-        [doc]: 'Code highlight theme (https://github.com/highlightjs/highlight.js/tree/master/src/styles)',
+        [doc]: 'Code highlight theme\nhttps://github.com/highlightjs/highlight.js/tree/master/src/styles',
         [defaultValue]: 'atom-one-light'
     },
     thumbnail: {

includes/specs/comment.spec.js

@@ -104,7 +104,7 @@ const ValineSpec = {
 
 module.exports = {
     [type]: 'object',
-    [doc]: 'Comment plugin settings (http://ppoffice.github.io/hexo-theme-icarus/categories/Configuration/Comment-Plugins)',
+    [doc]: 'Comment plugin settings\nhttp://ppoffice.github.io/hexo-theme-icarus/categories/Configuration/Comment-Plugins',
     type: {
         [type]: 'string',
         [doc]: 'Name of the comment plugin',

includes/specs/config.spec.js

@@ -18,6 +18,7 @@ module.exports = {
     search: require('./search.spec'),
     comment: require('./comment.spec'),
     share: require('./share.spec'),
+    sidebar: require('./sidebar.spec'),
     widgets: require('./widgets.spec'),
     plugins: require('./plugins.spec'),
     providers: require('./providers.spec')

includes/specs/meta.spec.js

@@ -22,7 +22,7 @@ module.exports = {
     },
     open_graph: {
         [type]: 'object',
-        [doc]: 'Open Graph metadata (https://hexo.io/docs/helpers.html#open-graph)',
+        [doc]: 'Open Graph metadata\nhttps://hexo.io/docs/helpers.html#open-graph',
         fb_app_id: {
             [type]: 'string',
             [doc]: 'Facebook App ID',

includes/specs/plugins.spec.js

@@ -10,17 +10,17 @@ module.exports = {
     },
     gallery: {
         [type]: 'boolean',
-        [doc]: 'Enable the lightGallery and Justified Gallery plugins (http://ppoffice.github.io/hexo-theme-icarus/2016/07/08/plugin/Gallery/)',
+        [doc]: 'Enable the lightGallery and Justified Gallery plugins\nhttp://ppoffice.github.io/hexo-theme-icarus/Plugins/General/gallery-plugin/',
         [defaultValue]: true
     },
     'outdated-browser': {
         [type]: 'boolean',
-        [doc]: 'Enable the Outdated Browser plugin (http://outdatedbrowser.com/)',
+        [doc]: 'Enable the Outdated Browser plugin\nhttp://outdatedbrowser.com/',
         [defaultValue]: true
     },
     mathjax: {
         [type]: 'boolean',
-        [doc]: 'Enable the MathJax plugin (http://ppoffice.github.io/hexo-theme-icarus/2018/01/01/plugin/MathJax/)',
+        [doc]: 'Enable the MathJax plugin\nhttp://ppoffice.github.io/hexo-theme-icarus/Plugins/General/mathjax-plugin/',
         [defaultValue]: true
     },
     'back-to-top': {
@@ -30,7 +30,7 @@ module.exports = {
     },
     'google-analytics': {
         [type]: ['boolean', 'object'],
-        [doc]: 'Google Analytics plugin settings (http://ppoffice.github.io/hexo-theme-icarus/2018/01/01/plugin/Analytics/#Google-Analytics)',
+        [doc]: 'Google Analytics plugin settings\nhttp://ppoffice.github.io/hexo-theme-icarus/Plugins/General/site-analytics-plugin/#Google-Analytics',
         tracking_id: {
             [type]: 'string',
             [doc]: 'Google Analytics tracking id',
@@ -39,7 +39,7 @@ module.exports = {
     },
     'baidu-analytics': {
         [type]: ['boolean', 'object'],
-        [doc]: 'Baidu Analytics plugin settings (http://ppoffice.github.io/hexo-theme-icarus/2018/01/01/plugin/Analytics/#Baidu-Analytics)',
+        [doc]: 'Baidu Analytics plugin settings\nhttp://ppoffice.github.io/hexo-theme-icarus/Plugins/General/site-analytics-plugin/#Baidu-Analytics',
         tracking_id: {
             [type]: 'string',
             [doc]: 'Baidu Analytics tracking id',
@@ -48,7 +48,7 @@ module.exports = {
     },
     hotjar: {
         [type]: ['boolean', 'object'],
-        [doc]: 'Hotjar user feedback plugin (http://ppoffice.github.io/hexo-theme-icarus/2018/01/01/plugin/Analytics/#Hotjar)',
+        [doc]: 'Hotjar user feedback plugin\nhttp://ppoffice.github.io/hexo-theme-icarus/Plugins/General/site-analytics-plugin/#Hotjar',
         site_id: {
             [type]: ['string', 'number'],
             [doc]: 'Hotjar site id',

includes/specs/providers.spec.js

@@ -2,7 +2,7 @@ const { doc, type, defaultValue } = require('../common/utils').descriptors;
 
 module.exports = {
     [type]: 'object',
-    [doc]: 'CDN provider settings',
+    [doc]: 'CDN provider settings\nhttp://ppoffice.github.io/hexo-theme-icarus/Configuration/Theme/speed-up-your-site-with-custom-cdn/',
     cdn: {
         [type]: 'string',
         [doc]: 'Name or URL of the JavaScript and/or stylesheet CDN provider',

includes/specs/search.spec.js

@@ -2,7 +2,7 @@ const { doc, type, defaultValue, required, requires } = require('../common/utils
 
 module.exports = {
     [type]: 'object',
-    [doc]: 'Search plugin settings (http://ppoffice.github.io/hexo-theme-icarus/categories/Configuration/Search-Plugins)',
+    [doc]: 'Search plugin settings\nhttp://ppoffice.github.io/hexo-theme-icarus/categories/Configuration/Search-Plugins',
     type: {
         [type]: 'string',
         [doc]: 'Name of the search plugin',

includes/specs/share.spec.js

@@ -2,7 +2,7 @@ const { doc, type, defaultValue, required, requires } = require('../common/utils
 
 module.exports = {
     [type]: 'object',
-    [doc]: 'Share plugin settings (http://ppoffice.github.io/hexo-theme-icarus/categories/Configuration/Share-Plugins)',
+    [doc]: 'Share plugin settings\nhttp://ppoffice.github.io/hexo-theme-icarus/categories/Configuration/Share-Plugins',
     type: {
         [type]: 'string',
         [doc]: 'Share plugin name',

includes/specs/sidebar.spec.js

@@ -0,0 +1,20 @@
+const { doc, type, defaultValue, required, requires, format } = require('../common/utils').descriptors;
+
+function commonSettings(position) {
+    return {
+        [type]: 'object',
+        [doc]: position + ' sidebar settings',
+        sticky: {
+            [type]: 'boolean',
+            [doc]: 'Whether the ' + position + ' sidebar is sticky when page scrolls\nhttp://ppoffice.github.io/hexo-theme-icarus/Configuration/Theme/make-a-sidebar-sticky-when-page-scrolls/',
+            [defaultValue]: false
+        }
+    }
+}
+
+module.exports = {
+    [type]: 'object',
+    [doc]: 'Sidebar settings.\nPlease be noted that a sidebar is only visible when it has at least one widget',
+    left: commonSettings('left'),
+    right: commonSettings('right')
+}

includes/specs/widgets.spec.js

@@ -121,7 +121,7 @@ const LinksSpec = {
 
 module.exports = {
     [type]: 'array',
-    [doc]: 'Sidebar widget settings (http://ppoffice.github.io/hexo-theme-icarus/categories/Widgets/)',
+    [doc]: 'Sidebar widget settings\nhttp://ppoffice.github.io/hexo-theme-icarus/categories/Widgets/',
     [defaultValue]: DEFAULT_WIDGETS,
     '*': {
         [type]: 'object',

layout/common/widget.ejs

@@ -17,12 +17,15 @@
 <% function order_class() {
     return position === 'left' ? 'has-order-1' : 'has-order-3';
 } %>
-<div class="column <%= side_column_class() %> <%= visibility_class() %> <%= order_class() %> column-<%= position %>">
+<% function sticky_class(position) {
+    return get_config('sidebar.' + position + '.sticky', false) ? 'is-sticky' : '';
+} %>
+<div class="column <%= side_column_class() %> <%= visibility_class() %> <%= order_class() %> column-<%= position %> <%= sticky_class(position) %>">
     <% get_widgets(position).forEach(widget => {%>
         <%- partial('widget/' + widget.type, { widget, post: page }) %>
     <% }) %>
     <% if (position === 'left') { %>
-        <div class="card card-transparent is-hidden-widescreen">
+        <div class="column-right-shadow is-hidden-widescreen <%= sticky_class('right') %>">
         <% get_widgets('right').forEach(widget => {%>
             <%- partial('widget/' + widget.type, { widget, post: page }) %>
         <% }) %>

source/css/style.styl

@@ -35,19 +35,25 @@ body, button, input, select, textarea
     .section
         padding: 1.5rem 1rem
 
-.column-main,
+@media screen and (min-width: screen-tablet)
-.column-left,
+    .column-main,
-.column-right
+    .column-left,
-    align-self: flex-start
+    .column-right,
-    &.is-sticky
+    .column-right-shadow
-        position: sticky
+        &.is-sticky
-        top: .75rem
+            align-self: flex-start
+            position: sticky
+            top: .75rem
+    .column-right-shadow
+        &.is-sticky
+            top: 1.5rem
 
 .card
     overflow: hidden
     border-radius: 4px
     box-shadow: 0 4px 10px rgba(0,0,0,0.05), 0 0 1px rgba(0,0,0,0.1)
-    & + .card
+    & + .card,
+    & + .column-right-shadow
         margin-top: 1.5rem
     &.card-transparent
         overflow: visible

source/js/animation.js

@@ -8,7 +8,9 @@
         element.style.opacity = '0';
     });
     document.querySelector('body > .navbar').style.transform = 'translateY(-100px)';
-    ['.column-main > .card', '.column-left > .card', '.column-right > .card'].map(function (selector) {
+    ['.column-main > .card',
+     '.column-left > .card, .column-right-shadow > .card',
+     '.column-right > .card'].map(function (selector) {
         $(selector).forEach(function (element) {
             element.style.transition = '0s';
             element.style.opacity = '0';
@@ -22,7 +24,9 @@
             element.style.transition = 'opacity 0.3s ease-out, transform 0.3s ease-out';
         });
         document.querySelector('body > .navbar').style.transform = 'translateY(0)';
-        ['.column-main > .card', '.column-left > .card', '.column-right > .card'].map(function (selector) {
+        ['.column-main > .card',
+         '.column-left > .card, .column-right-shadow > .card',
+         '.column-right > .card'].map(function (selector) {
             var i = 1;
             $(selector).forEach(function (element) {
                 setTimeout(function () {