---
title: Cosy Starter Guide
top: 1
categories:
  - Hexo
status: doing
---

[🇨🇳 中文文档](https://mozzie.cn/2023/10/20/Cosy%20%E5%85%A5%E9%97%A8/)


# Hexo Installation

Installing a `Hexo` theme is straightforward. Simply copy the `Hexo-theme-cosy` directory to the `themes` directory, and then modify the theme configuration in `Hexo`'s `_config.yml`.


```yml
# Locate the theme setting
theme: hexo-theme-cosy
```

## Acquiring Cosy

- Visit [Cosy's code repository](https://github.com/17px/hexo-theme-cosy/tree/main) to stay updated on the latest theme developments.
- Download `hexo-theme-cosy.zip` from the [releases page](https://github.com/17px/hexo-theme-cosy/releases).
- Extract it into your site's `themes` directory.
- Enable it in Hexo's `_config.yml`.

# Hexo Configuration

Adjust settings in `Hexo`'s `_config.yml`.

## Basic Configuration

```yml
# Website title
title: 17px blog
# Sidebar header
subtitle: "Mozzie"
# HTML meta description for SEO
description: ""
# HTML meta keywords for SEO
keywords:
# Copyright text displaying author's name
author: Mozzie

# Set your website URL here
url: https://mozzie.cn
```

## Language Switch

You can find different language files in `hex theme liner/languages`. If you want to switch languages, fill in the file name of `yml` in the `_config.yml` file

```yml
language: en
```

## Code Highlighting

Disable Hexo's default highlight.js syntax highlighting.

```yml
highlight:
  enable: false
  line_number: true
  auto_detect: false
  tab_replace: ""
  wrap: true
  hljs: false

prismjs:
  enable: true
  preprocess: true
  line_number: true
  line_threshold: 0
  tab_replace: ""
```

# Cosy Theme Configuration

💡 The following settings are based on the `_config.yml` under `hexo-theme-cosy`.

## Post Category Icons

In sequence, set the `svg` icons. You can get a wide variety of icons at [xicon](https://www.xicons.org/).

```yml
postCategoryIcons:
  - <svg>...</svg>
  - <svg>...</svg>
  - <svg>...</svg>
```

## Website Favicon

- Supports `svg`
- Supports `image URL`, e.g., `/img/favicon.png`

```yml
favicon: ''
```

## ICP Number 🇨🇳

😁 If not required, can be directly deleted.

```yml
icp: 苏ICP备xxxxxxx号-x
```

## Footer Text on Homepage 🇨🇳

😁 If not required, can be directly deleted or set to `false`.

```yml
motto: false
```

## Post Copyright Statement

Enabled by default. When `enable: false`, it is disabled by default.

```yml
postCopyright:
  enable: true
  license: CC BY-NC-SA 4.0
  license_url: https://creativecommons.org/licenses/by-nc-sa/4.0/
```

## Katex Mathematical Formulas

You can configure the CDN yourself.

```yml
katex:
  enable: true
  jsCdn: //cdn.jsdelivr.net/npm/katex@0.13.18/dist/katex.min.js
  cssCdn: //cdn.jsdelivr.net/npm/katex@0.13.18/dist/katex.min.css
```

## Mermaid Flowcharts

To draft flowchart syntax, use `{% mermaid %}` and `{% endmermaid %}` as wrappers.

```markdown
{% mermaid %}
graph TD;
    A --> B;
    A --> C;
    B --> D;
    C --> D;
{% endmermaid %}
```

Corresponding configurations are as follows:

```yml
mermaid:
  enable: true
  cdn: //cdn.jsdelivr.net/npm/mermaid@10.4.0/dist/mermaid.min.js
```

## Valine Comments

First, register as a `LeanCloud` international user and create a database.

Please proceed in accordance with relevant regional regulations.

```yml
valine:
  enable: true
  # 替换
  appId: appId
  # 替换
  appKey: appKey
  avatar: monsterid
  cdn: //unpkg.com/valine@latest/dist/Valine.min.js
  # 替换
  serverURLs: //xxxxxxxx.api.lncldglobal.com
```

# Algolia Search

The blog comes with built-in local search, based on frontend development, which may have some issues. It's recommended to switch to `Algolia`. The free account has a total of 10,000 records and 100,000 operations per month.

## Register & Acquire Key

1. Create a new `Index`, for example, `hex-blog`

2. Copy and save:
  - Application ID
  - Search-Only API Key
  - Admin API Key
  - Usage API Key

[API Keys](/img/algolia-api-keys.png)

3. Replace configurations

Add the following to Hexo's `_config.yml`

```yml
algolia:
  # Replace
  appId: Application ID
  # Replace
  apiKey: Usage API Key
  # Do not disclose, used for reporting, replace
  adminApiKey: Admin API Key
  # Replace
  SearchOnlyAPIKey: Search-Only API Key
  chunkSize: 5000
  # Replace
  indexName: hex-blog
  fields:
    - content:strip
    - categories
    - date
    - permalink
    - slug
    - tags
    - title
```

## Install hexo-algoliasearch

This is a Hexo blog post index plugin that automates the submission of indexes to Algolia.

> If you encounter any problems, you can read the [hexo-algoliasearch repository](https://www.npmjs.com/package/hexo-algoliasearch) for the latest instructions.

Installation command:

```bash
npm install hexo-algoliasearch --save
```

## Using Algolia

Before publishing each blog post, carry out index uploading operations. The usual commands are as follows:

```bash
hexo clean
hexo generate
hexo algolia
``` 


# QWeather Widget 🇨🇳

Cosy mainly targets domestic users and integrates QWeather cards on the homepage. Register via [QWeather Developer Service](https://dev.qweather.com/docs/start/).

After registering, fill in your `appKey` and `cityCode` in the configuration.

```yml
weather:
  enable: true
  # Replace
  cityCode: cityCode
  appKey: appKey
```

You can find your city's `cityCode` in the official region list repository's `China-City-List-latest.csv`.


# Front Matter

In Hexo's Markdown files, a typical YAML-formatted `Front Matter` might look like this:


```markdown
---
title: My Article Title
categories:
- javascript
tags: 
- Programming
- JavaScript
---
```

## top

To pin an article to the top, assign a numerical value to the `top` metadata. Articles with a specified `top` value will be marked with a 📌 icon in the category list.

For example, if there are three articles:

- Article 1

```markdown
---
title: Article 1
top: 0
categories:
  - javascript
---
```

- Article 2

```markdown
---
title: Article 2
top: 1
categories:
  - javascript
---
```

- Article 3

```markdown
---
title: Article 3
categories:
  - javascript
---
```

Then, under the `javascript` category, the sort order will be: `Article 1 > Article 2 > Article 3`.

## status

This is used to differentiate the status of articles and can be quickly `filtered` using the category list. The Cosy theme comes with 4 built-in statuses:

- done: Completed
- doing: In Progress
- todo: To Do
- other: Abandoned

For example:

```markdown
---
title: Article 1
categories:
- javascript
status: done
---
```