Skip to content

Latest commit

 

History

History
600 lines (447 loc) · 19.6 KB

README.en.md

File metadata and controls

600 lines (447 loc) · 19.6 KB

| 简体中文 | English | 日本語 |

hexo-theme-arknights

Preview

If you're using this theme, we will appreciate it if you could put your link here for a preview!

Preview image

Install

System requirements

Use hexo-cli to create a new blog project

hexo init Hexo
cd Hexo
npm install
git clone https://github.com/Yue-plus/hexo-theme-arknights.git themes/arknights --depth=1

Install dependencies

For npm users:

npm install hexo-server hexo-browsersync hexo-renderer-pug --save

For yarn users:

yarn add hexo-server hexo-browsersync hexo-renderer-pug

Edit configurations

  • Edit _config.yml under folder Hexo/. You can refer to Hexo.

    • Change the default value of theme: from landscape to arknights

    • Enable code highlighting:

      highlight:
  hljs: true

  • Move Hexo/themes/arknights/_config.yml to the root directory of Hexo, and rename it to _config.arknights.yml.

    Please refer to:

    The configuration file of the theme can be modified by referring to the Chinese comments.

Edit asset files

The following files can be added to the Hexo/source directory as needed:

  • CNAME: Custom domain name when GitHub Pages is deployed
  • The Alipay.png and WeChat.png in the img/ directory are your own QR codes (1:1 scale png images);

You can modify the Hexo/themes/arknights/source/ directory as needed:

  • favicon.ico: Icons on browser tabs (64*64, not displayed if the resolution is high)
  • README.md: README for deployment repository

Writing

  • Please refer to Hexo | Writing.

  • There are some sample texts available in the Hexo branch.

  • To add tags and categories, or for more features, please refer to Hexo | Front-matter. Example:

    ---
title: 'Hello World !'
date: 2020-04-15 21:54:02
tags: code
category: Example
---

  • The content before <!-- more --> is called a summary. It will be displayed on the home page, and you can set whether it is also displayed in the main body of the article.

Custom pages in the top navigation bar

  • Example: Creating an about page

    • Run the commands hexo new page 'about' in Hexo directory
    • Hexo will create an about folder in Hexo/source/

  • Edit file Hexo/source/about/index.md

  • Edit _config.arknights.yml, and add a link there:

    menu:
  About: /about

Disable Archive Page Turning

This setting is located in the Hexo configuration file _config.yml about line 88.

# Pagination
## Set per_page to 0 to disable pagination
per_page: 10
pagination_dir: page

Change per_page: to 0。

Comment systems

Valine

The theme supports Valine.
Please refer to Valine Quick Start and edit _config.arknights.yml in your Hexo directory:

valine:
  enable: false
  app_id: # APP ID
  app_key: # APP KEY
  server_url: # APP DOMAIN (LeanCloud international version requires this)
  avatar: 'retro' # (''/mp/identicon/monsterid/wavatar/robohash/retro/hide)
  avatar_cdn: 'https://dn-qiniu-avatar.qbox.me/avatar/' # Custom avatar cdn

For notifications with email: zhaojun1998 / Valine-Admin

Note! server_url: is ONLY required when using LeanCloud international version. This setting can be found in the LeanCloud application in Settings -> Application Credentials -> Domain Whitelist -> Request Domain for the domain name ending in '.api.lncldglobal.com' and add the 'https:' prefix.

Gitalk

The theme supports Gitalk . Please refer to gitalk/readme.md and edit _config.arknights.yml in your Hexo directory:

gitalk:
  enable: false
  client_id: # GitHub Application Client ID
  client_secret: # GitHub Application Client Secret
  repo: # GitHub repository
  owner: # GitHub repository owner
  admin: [] # GitHub repository owner and collaborators (Users who having write access to this repository)
            # Example: [adminA,adminB]
  id: # The unique id of the page
      # Example: location.pathname

Waline

The theme supports Waline.
Please refer to Waline docs and edit _config.arknights.yml in your Hexo directory

waline:
  enable: false 
  server_url: #Server_Url

Artalk

The theme supports Artalk.
Please refer to Artalk docs and edit _config.arknights.yml in your Hexo directory.

artalk:
  enable: false
  server: https://artalk.server.instance/ # 你的 Artalk 服务地址
  site_name: My Blog # 站点名称，用于区分多个站点（可选）

Mathematical formulas

The theme supports two scenarios for displaying math formulas:

Option 1: Static rendering

You can use hexo-filter-mathjax filter to render math formulas statically:

It is recommended to replace the markdown renderer hexo-renderer-pandoc that can better handle mathematical formulas first.

  1. Run the following commands in your Hexo directory:

    # Install hexo-filter-mathjax
cnpm install hexo-filter-mathjax --save
# Clean the cache
hexo clean

  2. Add the following into Hexo/_config.yml:

    mathjax:
  tags: none # or 'ams' or 'all'
  single_dollars: true # use single '$' as inline math formula delimiter
  cjk_width: 0.9 # Relatively CJK character width
  normal_width: 0.6 # Relatively normal width
  append_css: true # Add CSS to every pages
  every_page: false # If true, then every page will be rendered by mathjax, regardless of the `mathjax` setting in the front-matter of each article

  3. Add mathjax: true in the Front-matter of article that requires mathjax to be enabled:

    ---
title: On the Electrodynamics of Moving Bodies
categories: Physics
date: 1905-06-30 12:00:00
mathjax: true
---

    Then, you can use LaTeX in your articles.

  4. Please note that inline math formulas (… $<math formula>$ ...) cannot have spaces after the opening $ and before the closing $! For example:

    - $ \epsilon_0 $
+ $\epsilon_0$
- $ \frac{\partial}{\partial t} $
+ $\frac{\partial}{\partial t}$

  5. Be aware of the conflict between LaTeX and Markdown syntax. Use \ to escape if necessary:

    - $\epsilon_0$
+ $\epsilon\_0$
- \begin{eqnarray*}
+ \begin{eqnarray\*}

Option 2: Dynamic rendering

The theme also supports MathJax, to dynamically render formulas as the user browses:

  1. First, uninstall the hexo-renderer-marked renderer that comes with Hexo by default, and replace with hexo-renderer-kramed with better MathJax support:

    npm uninstall hexo-renderer-marked --save
npm install hexo-renderer-kramed --save

  2. Edit _config.arknights.yml in your Hexo directory:

      # Formula support
  mathjax:
-   enable: false
+   enable: true
    version: '2.6.1'  # important

  3. Then, you can use LaTeX in your articles:

    % Single-line inline formula
% Note that you need to put "`" on both sides, and there can be no space between "`" and "$"
`$\sigma$`

% Multi-line formula
$$
\begin{aligned}f(x) &= \sum_{i=1}^{\infty}{\frac{x}{2^i}} \\
&= x\end{aligned}
$$

  4. With this scheme, there will be no conflict between LaTeX and Markdown syntax. Escaping is not required to use LaTeX syntax in the text.
    The following formulas can be used directly without any problems:

    \epsilon_0
\begin{eqnarray*}

The hexo-renderer-kramed plugin has other configurable items, please refer to the plugin documentation: https://github.com/sun11/hexo-renderer-kramed

Advantages and disadvantages of these formula display schemes:

  1. Dynamic rendering does not require escaping, and can better support Markdown files exported from other places. But since it needs to be rendered in the browser, the page display will be slightly delayed.
  2. The static rendering compiles the formula directly into the static file, which has better display performance, but the syntax needs to be escaped.
  3. hexo-renderer-pandoc quickly displays formulas without having to go through the hassle of escaping syntax, but requires Pandoc to be installed.

Chart support

Edit _config.arknights.yml in your Hexo directory:

  # Chart support
  mermaid:
-   enable: false
+   enable: true
    version: '8.13.5'

The theme renders various charts via mermaid-js. Examples

Supports: Flow Chart | Sequence Diagram | Class Diagram | State Diagram | Entity Relationship Diagram | User Journey Map | Gantt Chart | Instruction Map | Pie Chart

Syntax:

<div class="mermaid">
  graph LR
  A[Hard edge] -->|Link text| B(Round edge)
  B --> C{Decision}
  C -->|One| D[Result one]
  C -->|Two| E[Result two]
</div>

It is also fully supported if you are used to using code blocks.

Word count & Reading time statistics

Depends hexo-wordcount:

For npm users:

cnpm install hexo-wordcount --save

For yarn users:

yarn add hexo-wordcount

Then edit _config.arknights.yml in your Hexo directory:

post:
  count: true # Display word count
  time: true # Display reading time statistics

Views statistics

Use 不蒜子 for page view statistics. Modify the _config.arknights.yml file in the Hexo directory to enable this feature:

busuanzi:
  enable: false
  sitePV: true # Total Site Visits
  siteUV: true # Number of site visitors
  pagePV: true # Page Views

Document encryption

The modified hexo-blog-encrypt plugin has been adapted and integrated into this theme (currently only the default and up themes are supported).

If previously installed, please remove the hexo-blog-encrypt dependency in package.json under the hexo directory and execute the following command

pnpm i
hexo clean

For detailed configuration reference hexo-blog-encrypt

Add the following to the Hexo/_config.yml file:

# Security
encrypt: # hexo-blog-encrypt
  abstract: Password required for weak neural connection to Rhodes Island™
  message: Please enter password for weak neural connection to Rhodes Island™
  tags:
  - {name: tagName, password: PassowrdA}
  - {name: tagName, password: PasswordB}
  wrong_pass_message: Failed to verify password with Rhodes Island™, please try again.
  wrong_hash_message: Failed to validate password with Rhodes Island™, currently viewing with temporary privileges.

Or Set the following in Front-matter of the artical:

---
title: Hello World
tags:
- Encrypted as a diary
date: 2016-03-30 21:12:21
password: mikemessi
abstract: Password required for weak neural connection to Rhodes Island™
message: Please enter password for weak neural connection to Rhodes Island™
wrong_pass_message: Failed to verify password with Rhodes Island™, please try again.
wrong_hash_message: Failed to validate password with Rhodes Island™, currently viewing with temporary privileges.
---

Searching

Searching is enabled by default. To disable it, edit your Hexo/_config.arknights.yml file:

search:
  enable: false

Front-matter

In addition to Front-matter supported by Hexo, the theme also supports:

# Article Published/updated date
post-time: true/false

# Article reading time/word count statistics
post-count: true/false

# Article busuanzi counter
busuanzi: true/false

# Turn on/off all of the above
post-info: true/false

# Sidebar table of contents
post-index: true/false

# Rewards
reward: true/false

extra label

admonition

{% note/warning/success/failure/detail [title] [open/fold] [color] %}
content
{% end[note/warning/success/failure/detail] %}

Add block based content such as note, warning, error, etc. with icons for note/warning/success/failure and no icons for detail.

hide

{% hide content %}

Hidden content, supports markdown rendering, can have spaces, and does not require quotation marks.

link card/linkc

{% linkcard %}
Title1:
    avatar: https://someLink/someAvatar.png
    src: https://someLink/
    img: https://somelink/somePicture.png
    descr: someDescr
    style:
    	color: someColor
Title2:
    avatar: https://someLink/someName.png
    src: https://someLink/
{% endlinkcard %}

A set of friendly links can be generated, with the title and link (src) as mandatory options. Style follows CSS format.

Import custom CSS/JS files

You can put your own CSS snippets into Hexo/source/css/;
put JavaScript file into Hexo/source/js/;

Then edit Hexo/_config.arknights.yml:

  # Include CSS stylesheets inside `<head>` tags
  stylesheets:
  - //unpkg.com/@highlightjs/[email protected]/styles/atom-one-dark-reasonable.min.css
+ - /css/custom.css
  
  # Introduce JavaScript at the end of `<body>`
  scripts:
  - //unpkg.com/@highlightjs/[email protected]/highlight.min.js
+ - /js/custom.js

The resource folder is where a user stores his resources.
With the exception of the _posts folder, files/folders and hidden files named starting with _ (underscore) will be ignored. Markdown and HTML files will be parsed and put into the public folder, while other files are copied over there.

-- From Hexo Official Documentation

Participate in the development

Welcome to submit Issues and PR

Branch description

Branch Illustrate
main A relatively stable version
gh-pages gh-page hosting
hexo Hexo directory, where you can fine .md files to test your theme

Bugs and solutions that may encounter during development

Modified TS file does not take effect

TypeScript needs to be compiled manually, please install typescript globally and execute tsc in the arknights\source\js\_src directory to compile it.

Long articles are not fully rendered when running 'hexo serve --debug'

This is caused by hexo-browsersync, and will not affect the release.

Workaround: Disable the plugin. (Anyway, it doesn't affect the release, no matter what)

Documentation that may be required to participate in the development

Developers

Reward

If you enjoy this theme: