From 2cb030d31c6c70e9ff0f41417858cbaebc914ec3 Mon Sep 17 00:00:00 2001 From: ppoffice Date: Mon, 20 Apr 2020 23:23:26 -0400 Subject: [PATCH] chore(doc): update docs --- .../_posts/demo/Hexo-Built-In-Tag-Helpers.md | 2 +- source/_posts/en/Configuring-Theme.md | 5 +- source/_posts/en/FAQ.md | 217 +++++++++++++++--- source/_posts/en/Getting-Started.md | 15 +- source/_posts/en/Other-Plugins.md | 30 +++ source/_posts/zh-CN/Configuring-Theme.md | 2 +- source/_posts/zh-CN/Getting-Started.md | 13 ++ source/_posts/zh-CN/Other-Plugins.md | 30 +++ 8 files changed, 272 insertions(+), 42 deletions(-) diff --git a/source/_posts/demo/Hexo-Built-In-Tag-Helpers.md b/source/_posts/demo/Hexo-Built-In-Tag-Helpers.md index 00f786e..358d2ca 100644 --- a/source/_posts/demo/Hexo-Built-In-Tag-Helpers.md +++ b/source/_posts/demo/Hexo-Built-In-Tag-Helpers.md @@ -200,7 +200,7 @@ Inserts an image with specified size. {% img [class names] /path/to/image [width] [height] [title text [alt text]] %} ``` -{% img /gallery/thumbnails/desert.jpg 100% 100% '"Desert" "Desert"' %} +{% img /gallery/thumbnails/vector_landscape_1.svg 100% 100% '"Vector Landscape" "Vector Landscape"' %} ## Link diff --git a/source/_posts/en/Configuring-Theme.md b/source/_posts/en/Configuring-Theme.md index 0d5fc25..669445f 100644 --- a/source/_posts/en/Configuring-Theme.md +++ b/source/_posts/en/Configuring-Theme.md @@ -13,9 +13,8 @@ toc: true Icarus' default theme configuration file `_config.yml` resides in the `themes/icarus` directory. It defines the global layout and style settings of the theme as well as external features such as comment plugins and widgets. -In this post, we will be covering settings that relate to the styling and overall layout of your site. -We will be covering the mechanisms used by Icarus to configure your site and going through the format and meaning of some configuration -settings. +In this post, we will cover the mechanisms used by Icarus to configure your site and going through the format +and meaning of some configuration settings. diff --git a/source/_posts/en/FAQ.md b/source/_posts/en/FAQ.md index 5aaef90..a9a4b55 100644 --- a/source/_posts/en/FAQ.md +++ b/source/_posts/en/FAQ.md @@ -1,54 +1,203 @@ title: FAQ date: 2020-02-01 thumbnail: /gallery/thumbnails/vector_landscape_3.svg +toc: true --- -### How do I put text instead of an image as my site's logo? +The article presents some of the frequently asked questions about Icarus and their solutions. +Please also read through the [Icarus User Guide](/hexo-theme-icarus/tags/Icarus-User-Guide/), +[Hexo documentation](https://hexo.io/docs/index.html) and +[Icarus GitHub Issues](https://github.com/ppoffice/hexo-theme-icarus/issues?q=) if you cannot find +the answer to your question here. -If you consider using a piece of text instead of an image as the logo of your site, you can do something like this: - -{% codeblock lang:yaml _config.yml %} -logo: - text: My Beautiful Site -{% endcodeblock %} -### How do I change the site's language? -Edit your blog's `_config.yml`(not your theme's), change the following field: -```diff + + + +## Site + +
+
+My Hexo site is not generating./There are errors when generating my site. +
+
+ +Icarus requires Node.js of version 8.3.0 and above, Hexo of version 4.2.0 and above, and some other +package dependencies listed in the `peerDependencies` section of the +[`themes/icarus/package.json`](https://github.com/ppoffice/hexo-theme-icarus/blob/master/package.json) +file. +Please make sure you meet all the dependency requirements. +Also, it is possible that dependencies of the previous theme you used could interfere with Icarus. +Please remove them before you switch to Icarus. + +
+
+How do I change the language of my site? +
+
+ +Edit your site's `_config.yml` under the root directory, change the following setting: + +{% codeblock _config.yml lang:diff %} - language: en -+ language: zh-CN -``` ++ language: +{% endcodeblock %} -You can find available translations under `icarus/languages` folder. +You can find available translations under the `themes/icarus/languages` directory. +The file name without file extension is the language name used in `_config.yml`. -### How to add an excerpt for a post? How to display the "Read more" button? -Add `` tag in your post. Post content before this tag will be marked as an excerpt and content after this tag will not show on the index page. -### Why aren't my changes deployed to the Github Pages? -Please run these commands before `hexo deploy`: +## Layout -```bash -$ hexo clean -$ rm -r .deploy_git -``` +
+
+How do I change the width of the page? How do I use a one/two/three-column layout in certain posts/pages? +
+
-### How to add meta tags for a specified post/page? +To change the width of the page, you need to edit the style file located at `themes/icarus/include/style/responsive.styl`. +This file defines the container width under different screen sizes. +If you also want to change the column width of the widgets or the main content, please go to `themes/icarus/layout/common/widgets.jsx` and `themes/icarus/layout/layout.jsx`. +Find the CSS class names like `is-12`, `is-8-tablet`, and `is-4-widescreen`. +Change the number in these class names to the one you want. -You can add meta tags for each post/page through front-matter: +You can refer to the [Bulma documentation](https://bulma.io/documentation/columns/sizes/) for more details on the +column system. +Please make sure the number of widget columns and the main content column add up to 12 under the same screen size. +For example, if you change the width of the widget column to `is-3-widescreen` and you only have one widget column, +you need to make sure your main content column has a `is-9-widescreen`. -```diff -title: test post -date: 2015-01-26 21:55:37 -tags: -comments: false -+ meta: -+ - name="robots";content="noindex, follow" -+ - name="another-meta";value="hello world";enabled=false -``` +You can create a one-column layout by removing all widgets from your theme configurations. +To use a two-column layout, please move all your widgets to the same side of the page by setting their `position` +to `left` or `right`. +The three-column layout can be achieved by placing widgets on both sides of the page. -### Does this theme support RTL(Right-to-Left) language? +To change the layout in certain posts or pages, please refer to the +[Icarus User Guide - Configuring the Theme](/hexo-theme-icarus/Configuration/icarus-user-guide-configuring-the-theme/#Additional-Configuration-Files-and-Priority). + +
+
+Where are the layout files for widgets/comments/share...? How do I customize built-in widgets/comments/share...? +
+
+ +The layout files for comment plugins, donate buttons, site search, share buttons, widgets, and some other plugins +have been moved to a separate Node.js package called [`hexo-component-inferno`](https://github.com/ppoffice/hexo-component-inferno). +In doing this, the theme developers can better reuse common components across different themes and allow users to +override these built-in components easily. + +To customize these components, you may copy the layout files from the `hexo-component-inferno` repository and place +them in the corresponding directories under the Icarus layout directory. +For example, if you want to customize the Valine comment plugin, you can copy +[`src/view/comment/valine.jsx`](https://github.com/ppoffice/hexo-component-inferno/blob/0.2.4/src/view/comment/valine.jsx) +from the `hexo-component-inferno` repository and place it in the `themes/icarus/layout/comment` directory. +Then, fix some of the Node.js imports in the head of the file. + +{% codeblock themes/icarus/layout/comment/valine.jsx lang:diff %} +- const { cacheComponent } = require('../../util/cache'); ++ const { cacheComponent } = require('hexo-component-inferno/lib/util/cache'); +{% endcodeblock %} + +After that, `hexo clean` your site and regenerate the HTML files. + +Similarly, you can override static files by copying them from the `hexo-component-inferno` repository and place them +to the corresponding directory under `themes/icarus/source`. + +
+
+I changed something in the layout files. +But why didn't the changes take effect when I refresh the page (when using hexo s)/when I hexo generate? +
+
+ +The layout files are cached when you start a local Hexo server with `hexo server`. +Other times some intermediate data is cached in the `db.json` or memory. +Please use `hexo clean` before `hexo server` or `hexo generate`. + + +## Content + +
+
+My logo/images are not showing up./My images only shows in index pages but not posts. +
+
+ +Please make sure you use the absolute paths of your images. +For example, if you put your images under `source/gallery/`, and your site is in a +subdirectory of your domain name like `https://ppoffice.github.io/hexo-theme-icarus`, +you should include your image like this: `/hexo-theme-icarus/gallery/.`. + +You can also use the Hexo `{% img %}` tag to omit the subdirectory part of your image path: +{% img /gallery/<file_name>.<file_extension> ... %}. +Please refer to the [Hexo documentation](https://hexo.io/docs/tag-plugins#Image) for more details. + +
+
+How to add an excerpt for a post? How to display the "Read more" button? +
+
+ +Add `` tag in your post. +Post content before this tag will be marked as an excerpt and content after this tag will not show on the index page. +You may also add custom excerpt by specifying it in the post's front-matter. + +{% codeblock some-post.md lang:yaml %} +title: Some Post +date: 2020-01-01 +excerpt: This is an article about ... +--- +# Post content... +{% endcodeblock %} + +
+
+How do I encrypt my posts? +
+
+ +Please use third-party Hexo plugins like [hexo-blog-encrypt](https://github.com/MikeCoder/hexo-blog-encrypt). + +
+
+How do I use fancy elements and styling in my posts just like this one? +
+
+ +You can use raw HTML in your Markdown posts. +Please refer to the [Bulma documentation](https://bulma.io/documentation/) for more details on available +elements and styles. + + +## Widgets and Plugins + +
+
+My page is showing red alerts, saying that some settings are not set for a plugin/widget. +How can I get rid of them? +
+
+ +If you don't want to enable some plugins/widgets, you can simply delete them or comment them out in the +configurations. +For example, if you don't want to enable any comment plugin, just delete these lines: + +{% codeblock themes/icarus/_config.yml lang:diff %} +- comment: +- type: disqus +- shortname: ++ # comment: ++ # type: disqus ++ # shortname: +{% endcodeblock %} + + +
+Something wrong with this article? Click here to submit your revision. +
-Partially yes. Please refer to [Issues#234](https://github.com/ppoffice/hexo-theme-icarus/issues/234) Vector Landscape Vectors by Vecteezy \ No newline at end of file diff --git a/source/_posts/en/Getting-Started.md b/source/_posts/en/Getting-Started.md index 5e9b4d0..9f80086 100644 --- a/source/_posts/en/Getting-Started.md +++ b/source/_posts/en/Getting-Started.md @@ -7,7 +7,7 @@ tags: language: en --- Icarus is a simple, delicate, and modern theme for the static site generator Hexo. -It allows you to set up a single or multiple-column (up to three column) blog with its versatile layout configuration. +It allows you to set up a single or multiple-column (up to three columns) blog with its versatile layout configuration. Additionally, it offers plentiful plugins and pluggable widgets so that you can enable the features you want in no time. And with the all-new API designing, Icarus makes the development of this theme painless for developers and users. @@ -26,7 +26,7 @@ git clone https://github.com/ppoffice/hexo-theme-icarus.git themes/icarus -b ` to get the latest development version of Icarus. -You may also leave `--depth 1` out if you want to download full Git history if Icarus as well. +You may also leave `--depth 1` out if you want to download full Git history of Icarus as well. Furthermore, you can install Icarus as a Git submodule by executing the following command: {% codeblock "Git Bash/Shell" %} @@ -56,10 +56,19 @@ about Icarus and its configuration. Also, you can refer to the source code of this site for more examples by fetching the [`site` branch](https://github.com/ppoffice/hexo-theme-icarus/tree/site) of Icarus from GitHub. +**Additional Resources** + +The following are some additional resources that can help you take a step further into customizing your site. +You can also add a link to your Icarus tutorial below by click [this link](https://github.com/ppoffice/hexo-theme-icarus/edit/site/source/_posts/en/Getting-Started.md). + +
+ Hexo documentation +
+ +
Something wrong with this article? Click here to submit your revision.
- Vector Landscape Vectors by Vecteezy diff --git a/source/_posts/en/Other-Plugins.md b/source/_posts/en/Other-Plugins.md index 8b11db3..52c1f63 100644 --- a/source/_posts/en/Other-Plugins.md +++ b/source/_posts/en/Other-Plugins.md @@ -120,6 +120,33 @@ This is another block expression: \\[f(x) = \int_{-\infty}^\infty\hat f(\xi)e^{2 \pi i \xi x}d\xi\\] {% endcodeblock %} +Sometimes your \\(\TeX\\) syntax will be mistaken as Markdown syntax, which will result in rendering error. +For instance, the following equation will not work since it contains more than one `_` (underscores), +which are mistaken for the italic text when processed by the Markdown renderer: + +{% codeblock Some-Post.md lang:tex %} +$$ +\hat{x}_{k}=\hat{x}_{k}^{-}+K_{t}\left(y_{k}\right) +$$ +{% endcodeblock %} + +In this case, you can either escape every character that may cause confusion: + +{% codeblock Some-Post.md lang:tex %} +$$ +\hat{x}\_{k}=\hat{x}\_{k}^{-}+K\_{t}\left(y\_{k}\right) +$$ +{% endcodeblock %} + +or simply wrap the whole equation with an additional HTML tag: + +{% codeblock Some-Post.md lang:tex %} +
+$$ +\hat{x}_{k}=\hat{x}_{k}^{-}+K_{t}\left(y_{k}\right) +$$ +
+{% endcodeblock %} ## MathJax @@ -222,6 +249,9 @@ Expressions should be wrapped in \\` in this case. When \`a != 0\`, there are two solutions to \`ax^2 + bx + c = 0\` and they are

\`x = (-b +- sqrt(b^2-4ac))/(2a)\`.

{% endcodeblock %} +Sometimes your latex syntax will be mistaken as Markdown syntax, which will result in rendering error. +Please refer to the [KaTeX](#KaTeX) section for solutions to this. + **Preview(\\(\TeX\\) & \\(\LaTeX\\))** This is an inline expression: \\(ax^2+bx+c=0\\). This is another inline expression: $ax^2+bx+c>0$. diff --git a/source/_posts/zh-CN/Configuring-Theme.md b/source/_posts/zh-CN/Configuring-Theme.md index 8392ffb..d0c25aa 100644 --- a/source/_posts/zh-CN/Configuring-Theme.md +++ b/source/_posts/zh-CN/Configuring-Theme.md @@ -68,7 +68,7 @@ WARN [ - 文章/页面的[front-matter](https://hexo.io/docs/front-matter.html) - 根目录下的站点配置文件`_config.yml` -`_config.post.yml`和`_config.page.yml`配置文件与默认配置文件的格式和定义想吐。 +`_config.post.yml`和`_config.page.yml`配置文件与默认配置文件的格式和定义相同。 你可以在`_config.post.yml`中设置仅对文章页面生效的配置，而这些配置将覆盖默认配置文件中的同名配置。 例如，你可以在此配置文件中把所有的挂件放置在页面左侧，从而将所有的文章页面设置为两栏布局，同时其他页面仍保持三栏布局： diff --git a/source/_posts/zh-CN/Getting-Started.md b/source/_posts/zh-CN/Getting-Started.md index 6b6c0b3..1d5965b 100644 --- a/source/_posts/zh-CN/Getting-Started.md +++ b/source/_posts/zh-CN/Getting-Started.md @@ -57,6 +57,19 @@ hexo s 您可以继续阅读[Icarus用户指南](/hexo-theme-icarus/tags/Icarus用户指南/)系列文章来了解Icarus的使用与配置。 同时，您可以从Icarus的[`site`分支](https://github.com/ppoffice/hexo-theme-icarus/tree/site)上获取本网站的源码供您参考。 +**额外资源** + +下面的一些资源可以帮助你进一步个性化你的站点。 +你也可以[点击此处](https://github.com/ppoffice/hexo-theme-icarus/edit/site/source/_posts/en/Getting-Started.md)来提交你的Icarus个性化配置教程。 + +
+ Hexo中文文档 + 博客源码分享 by 辣椒の酱 + hexo-theme-icarus 3 食用经验分享 by iMaeGoo +
+ +
+
文章内容有误？请点击此处提交修改。
diff --git a/source/_posts/zh-CN/Other-Plugins.md b/source/_posts/zh-CN/Other-Plugins.md index 7b8d21a..6371946 100644 --- a/source/_posts/zh-CN/Other-Plugins.md +++ b/source/_posts/zh-CN/Other-Plugins.md @@ -116,6 +116,33 @@ $$\displaystyle \frac{1}{\Bigl(\sqrt{\phi \sqrt{5}}-\phi\Bigr) e^{\frac25 \pi}} \\[f(x) = \int_{-\infty}^\infty\hat f(\xi)e^{2 \pi i \xi x}d\xi\\] {% endcodeblock %} +有时你的\\(\TeX\\)语法会被错认为Markdown语法而导致公式渲染异常。 +例如，下面的公式不会渲染成功，因为其中包含多个`_`(下划线)而被Markdown渲染器错误的认成Markdown的斜体字语法。 + +{% codeblock Some-Post.md lang:tex %} +$$ +\hat{x}_{k}=\hat{x}_{k}^{-}+K_{t}\left(y_{k}\right) +$$ +{% endcodeblock %} + +在这种情况下，你可以选择转义每个可能导致歧义的字符： + +{% codeblock Some-Post.md lang:tex %} +$$ +\hat{x}\_{k}=\hat{x}\_{k}^{-}+K\_{t}\left(y\_{k}\right) +$$ +{% endcodeblock %} + +或是简单的将整个公式用一个HTML标签包裹起来： + +{% codeblock Some-Post.md lang:tex %} +
+$$ +\hat{x}_{k}=\hat{x}_{k}^{-}+K_{t}\left(y_{k}\right) +$$ +
+{% endcodeblock %} + ## MathJax @@ -212,6 +239,9 @@ A = 当\`a != 0\`，方程\`ax^2 + bx + c = 0\`有两个解，它们是

\`x = (-b +- sqrt(b^2-4ac))/(2a)\`.

{% endcodeblock %} +有时你的\\(\TeX\\)语法会被错认为Markdown语法而导致公式渲染异常。 +请参照[KaTeX](#KaTeX)一节来解决此问题。 + **效果预览(\\(\TeX\\) & \\(\LaTeX\\))** 这是一个行内公式：\\(ax^2+bx+c=0\\)。这是另一个行内公式：$ax^2+bx+c>0$。