Skip to content

Latest commit

 

History

History
488 lines (363 loc) · 15.7 KB

README.en.md

File metadata and controls

488 lines (363 loc) · 15.7 KB
Raw

| 简体中文 | 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

System requirements

Install

Use hexo-cli to create a new blog project

(and clone this repo into it)

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

Note: For cnpm users, please replace npm with cnpm. Same below.

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 value of theme: 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

These files in folder Hexo/themes/arknights/source/ can be modified as needed:

  • favicon.ico:Icons on browser tabs
  • CNAME: Custom domain name when GitHub Pages is deployed
  • README.md: README for deployment repository
  • Alipay.png and WeChat.png in folder img/ can be replaced with your own reward QR code (1:1 scale png image);

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 following commands in Hexo directory 
    hexo new page 'about'
    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

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)

For notifications with email: zhaojun1998 / Valine-Admin

Note! server_url: is ONLY required when using LeanCloud international version .

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

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:

  1. Run the following commands in your Hexo directory:
# Install hexo-filter-mathjax
cnpm install hexo-filter-mathjax --save
# Clean the cache
hexo clean
  1. 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
  1. 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.

  1. 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}$
  1. 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
  1. Edit _config.arknights.yml in your Hexo directory:
# Formula support
mathjax:
-  enable: false
+  enable: true
  version: '2.6.1'  # important
  1. 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}
$$
  1. 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.

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

Document encryption

Note: Front-end encryption is not reliable!

Note! This encryption plugin encrypts the digest content, so it is not possible to hide digests in the body when using this plugin. In _config.arknights.yaml:

post:
  excerpt: true # Whether to show digest in the article(contents before <!-- more--> )   <===== cannot be false

You can try the hexo-blog-encrypt plugin for document encryption.

Detailed reference: hexo-blog-encrypt/ReadMe.md

cnpm install hexo-blog-encrypt --save

Add the following into Hexo/_config.yml:

# 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}
  template: <div id="hexo-blog-encrypt" data-wpm="{{hbeWrongPassMessage}}" data-whm="{{hbeWrongHashMessage}}"><div class="hbe-input-container"><input type="password" id="hbePass" placeholder="{{hbeMessage}}" /><label>{{hbeMessage}}</label><div class="bottom-line"></div></div><script id="hbeData" type="hbeData" data-hmacdigest="{{hbeHmacDigest}}">{{hbeEncryptedData}}</script></div>
  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:

# Published/updated date in the top right corner of the article page
post-info: true/false

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

# Rewards
reward: true/false

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

Contribute

Developers

Welcome to submit Issues and PR

Branch description

分支 说明
main A relatively stable version
dev Development 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

This is because after splitting the file, JavaScript is compiled manually instead. Please install typescript and run tsc in arknights\source\js to compile.

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

This is caused by hexo-browsersync, and will not affect the release.
Workaround: Just disable this plugin since it doesn't affect the release.

Reward

If you enjoy this theme:

  • give me a star (/▽＼)
  • Arknights ID of the developer: 24444750 (Chinese Bilibili server)
  • join Tencent QQ discussion group:618221514
  • reward/sponsor:

Reward QR code