Browse Source

move docs in to repo (#33)

pull/35/head
Cian Butler 5 years ago
committed by CSmartt
parent
commit
4464bb4e9f
12 changed files with 491 additions and 2 deletions
  1. +2
    -2
      README.md
  2. +40
    -0
      docs/Comment.md
  3. +88
    -0
      docs/Configuration.md
  4. +34
    -0
      docs/FAQ.md
  5. +26
    -0
      docs/Installation.md
  6. +20
    -0
      docs/Miscellaneous.md
  7. +35
    -0
      docs/Plugins.md
  8. +16
    -0
      docs/README.md
  9. +36
    -0
      docs/Search.md
  10. +39
    -0
      docs/Share.md
  11. +127
    -0
      docs/Theme.md
  12. +28
    -0
      docs/Widgets.md

+ 2
- 2
README.md View File

@@ -1,10 +1,10 @@
#Icarus

### The blog theme you may fall in love with, coming to Hexo.
### The blog theme you may fall in love with, coming to Hexo.
### Click here to [Preview](https://alpha.redbrick.dcu.ie/) the theme.
![](http://image.prntscr.com/image/4db6552e12434ae9b405bb301f864a1b.png "")

#### [View Documentation](https://wiki.redbrick.dcu.ie/mw/Main_Page)
#### [View Documentation](./docs)
:star: It is strongly recommended that you read the docs before using Icarus.

## Features


+ 40
- 0
docs/Comment.md View File

@@ -0,0 +1,40 @@
### Disqus
> ![Disqus](https://ooo.0o0.ooo/2016/02/08/56b884a1e2bc6.png)

You need to have a [Disqus](https://disqus.com/) account before using it in Icarus.

Then you should enter your site's Disqus shortname in the configuration. The Disqus shortname can be found at your site's Disqus general settings page:

> ![Disqus Shortname](https://ooo.0o0.ooo/2016/02/08/56b885366e79c.png)

```yaml
disqus: hexo-theme-icarus
```

### Duoshuo
> ![Duoshuo](https://ooo.0o0.ooo/2016/01/14/569794cf7e2b3.png)

You need to have a [Duoshuo](http://duoshuo.com/) account before using it in Icarus.

Then you should enter your site's Duoshuo shortname in the configuration. The Duoshuo shortname can be found at your Duoshuo settings page:

![Duoshuo Shortname](https://ooo.0o0.ooo/2016/02/08/56b885ae0daac.png)

```yaml
duoshuo: icarus
```

### YouYan
> ![YouYan](https://ooo.0o0.ooo/2016/01/14/56979c175e8c8.png)

> YouYan comment box cannot be displayed under the local environment. Please deploy your site and see if the configuration takes effect.

You need to hvae a [YouYan](http://www.uyan.cc/) account before using it in Icarus.

Then you should enter your site's YouYan user ID in the configuration. The YouYan user ID can be found at your YouYan admin page:

![YouYan User ID](https://ooo.0o0.ooo/2016/01/14/56979c628177d.png)

```yaml
youyan: 6666666
```

+ 88
- 0
docs/Configuration.md View File

@@ -0,0 +1,88 @@
Let's take a look at an example configuration file:

```yaml
# Menus
menu:
Home: .
Archives: archives
Categories: categories
Tags: tags
About: about

# Customize
customize:
logo:
enabled: true
width: 40
height: 40
url: images/logo.png
profile:
enabled: true # Whether to show profile bar
avatar: css/images/avatar.png
gravatar: # Gravatar email address, if you enable Gravatar, your avatar config will be overriden
author: PPOffice
author_title: Web Developer & Designer
location: Harbin, China
follow: https://github.com/ppoffice/
highlight: monokai
sidebar: right # sidebar position, options: left, right
thumbnail: true # enable posts thumbnail, options: true, false
favicon: # path to favicon
social_links:
github: http://github.com/ppoffice/hexo-theme-icarus
twitter: /
facebook: /
dribbble: /
rss: /
social_link_tooltip: true # enable the social link tooltip, options: true, false

# Widgets
widgets:
- recent_posts
- category
- archive
- tag
- tagcloud
- links

# Search
search:
insight: true # you need to install `hexo-generator-json-content` before using Insight Search
swiftype: # enter swiftype install key here
baidu: false # you need to disable other search engines to use Baidu search, options: true, false

# Comment
comment:
disqus: hexo-theme-icarus # enter disqus shortname here
duoshuo: # enter duoshuo shortname here
youyan: # enter youyan uid here

# Share
share: default # options: jiathis, bdshare, addtoany, default

# Plugins
plugins:
lightgallery: true # options: true, false
google_analytics: # enter the tracking ID for your Google Analytics
google_site_verification: # enter Google site verification code
baidu_analytics: # enter Baidu Analytics hash key

# Miscellaneous
miscellaneous:
open_graph: # see http://ogp.me
fb_app_id:
fb_admins:
twitter_id:
google_plus:
links:
Hexo: http://hexo.io
```

These configurations will be explained in the following chapters:
* [Theme](https://github.com/ppoffice/hexo-theme-icarus/wiki/Theme)
* [Widgets](https://github.com/ppoffice/hexo-theme-icarus/wiki/Widgets)
* [Search](https://github.com/ppoffice/hexo-theme-icarus/wiki/Search)
* [Comment](https://github.com/ppoffice/hexo-theme-icarus/wiki/Comment)
* [Share](https://github.com/ppoffice/hexo-theme-icarus/wiki/Share)
* [Plugins](https://github.com/ppoffice/hexo-theme-icarus/wiki/Plugins)
* [Miscellaneous](https://github.com/ppoffice/hexo-theme-icarus/wiki/Miscellaneous)

+ 34
- 0
docs/FAQ.md View File

@@ -0,0 +1,34 @@
### How do I change the site's language?
Edit your blog's `_config.yml`(not your theme's), change the following field:

```diff
- language: en
+ language: zh-CN
```

You can find available translation under `icarus/languages` folder.

### How to add excerpt for a post?
Add `<!-- more -->` tag in your post. Post content before this tag will be marked as excerpt.

### Why aren't my changes deployed to the Github Pages?
Please run these commands before `hexo deploy`:

```bash
$ hexo clean
$ rm -r .deploy_git
```

### How to add meta tags for a specified post/page?

You can add meta tags for each post/page through front-matter:

```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
```

+ 26
- 0
docs/Installation.md View File

@@ -0,0 +1,26 @@
1. Go to your blog's root folder and clone Icarus into `themes/icarus`:

```bash
$ git clone https://github.com/ppoffice/hexo-theme-icarus.git themes/icarus
```

2. Edit your blog's `_config.yml`, change the `theme` field to `icarus` to enable this theme:

```yaml
theme: icarus
```

3. Rename `_config.yml.example` in the theme folder to `_config.yml`.

4. (Optional) Don't forget to checkout the latest version once in a while:

```
$ cd themes/icarus
$ git pull
```

5. (Optional) To enable [Insight Search](https://github.com/ppoffice/hexo-theme-icarus/wiki/Search#insight-search) as your default search engine, you should also install `hexo-generator-json-content` from npm.

```
$ npm install -S hexo-generator-json-content
```

+ 20
- 0
docs/Miscellaneous.md View File

@@ -0,0 +1,20 @@
### Open Graph
About Open Graph: [Open Graph protocol](https://en.wikipedia.org/wiki/Facebook_Platform#Open_Graph_protocol)

Available options are listed below:

```yaml
open_graph:
fb_app_id:
fb_admins:
twitter_id:
google_plus:
```

### Links
Add links to your sidebar links widget.

```yaml
links:
Hexo: http://hexo.io
```

+ 35
- 0
docs/Plugins.md View File

@@ -0,0 +1,35 @@
### lightgallery
[lightgallery.js](https://sachinchoolur.github.io/lightgallery.js/) is a full featured javascript lightbox gallery with no dependencies. Set `true` to the configuration will enable LightGallery.

![lightgallery.js](https://ooo.0o0.ooo/2016/10/20/5808cf395dfdc.png)

```yaml
lightgallery: true
```

### Justified Gallery
[Justified Gallery](https://sachinchoolur.github.io/lightgallery.js/) is a JQuery plugin that allows you to create an high quality justified gallery of images. Set `true` to the configuration and wrap your images with `<div class="justified-gallery"></div>` will enable Justified Gallery.

![Justified Gallery](https://ooo.0o0.ooo/2016/10/20/5808cf3903056.png)

```yaml
justifiedgallery: true
```

### Google Analytics
Enter your Google Analytics tracking ID in the configuration file will enable this Google Analytics for your site. Tracking ID can be found in Google Analytics admin page.

```yaml
google_analytics: UA-66666666-6
```

![Google Analytics](https://ooo.0o0.ooo/2016/01/14/569786a78e160.png)

### Baidu Analytics
Enter your Baidu Analytics hash key in the configuration file will enable this Baidu Analytics for your site. Baidu Analytics hash key can be found in the `Get JS` section.

```yaml
baidu_analytics: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

![Google Analytics](https://ooo.0o0.ooo/2016/01/14/569786a787f06.png)

+ 16
- 0
docs/README.md View File

@@ -0,0 +1,16 @@
The blog theme you may fall in love with, coming to Hexo.

* [Installation](https://github.com/ppoffice/hexo-theme-icarus/wiki/Installation)
* [Configuration](https://github.com/ppoffice/hexo-theme-icarus/wiki/Configuration)
* [Theme](https://github.com/ppoffice/hexo-theme-icarus/wiki/Theme)
* [Widgets](https://github.com/ppoffice/hexo-theme-icarus/wiki/Widgets)
* [Search](https://github.com/ppoffice/hexo-theme-icarus/wiki/Search)
* [Comment](https://github.com/ppoffice/hexo-theme-icarus/wiki/Comment)
* [Share](https://github.com/ppoffice/hexo-theme-icarus/wiki/Share)
* [Plugins](https://github.com/ppoffice/hexo-theme-icarus/wiki/Plugins)
* [Miscellaneous](https://github.com/ppoffice/hexo-theme-icarus/wiki/Miscellaneous)
* [FAQ](https://github.com/ppoffice/hexo-theme-icarus/wiki/FAQ)

If you have any questions about Icarus, you can post it to [Issue Section](https://github.com/ppoffice/hexo-theme-icarus/issues).

And if you have a better idea about this theme, please feel free to make a [Pull Request](https://github.com/ppoffice/hexo-theme-icarus/pulls).

+ 36
- 0
docs/Search.md View File

@@ -0,0 +1,36 @@
### Insight Search
![Insight Search](https://ooo.0o0.ooo/2016/04/07/57068467ad5ea.png)

You can use <kbd>Esc</kbd> to close the search box, <kbd>↑</kbd>, <kbd>↓</kbd> to navigate between search results, and <kbd>Enter</kbd> to go to the selected result.

```yml
insight: true
```

> Attention: You need to install `hexo-generator-json-content` before using Insight Search.

> ```
> $ npm install -S hexo-generator-json-content
> ```

### Swiftype
![Swiftype](https://ooo.0o0.ooo/2016/02/08/56b883cdd2e17.png)

You need to have a [Swiftype](https://swiftype.com/) account before using it in Icarus.

``` yml
swiftype: XXXXXXXXXXXXXXXXXXXX
```

This `install key` can be found at your own engine's install page:

![](http://ppoffice.github.io/hexo-theme-icarus/gallery/swiftype_install.jpg "")

Finally, don't forget to save your swiftype configuration to complete the installation.

### Baidu (Not Recommended)

```yaml
baidu: true
```
And this should do the work.

+ 39
- 0
docs/Share.md View File

@@ -0,0 +1,39 @@
Share buttons will show at the end of your article and above the comment section. Icarus provide several share plugins, and each of them is adjusted in style in accord with the theme.

Available options:
* default
* addtoany
* jiathis
* bdshare

### Default

```yaml
share: default
```

![Default](https://ooo.0o0.ooo/2016/01/14/56978c2ddb1f1.png)

### AddToAny

```yaml
share: addtoany
```

![AddToAny](https://ooo.0o0.ooo/2016/01/14/56978c8908dc0.png)

### JiaThis

```yaml
share: jiathis
```

![JiaThis](https://ooo.0o0.ooo/2016/01/14/56978cdd41f52.png)

### Baidu Share

```yaml
share: bdshare
```

![Baidu Share](https://ooo.0o0.ooo/2016/01/14/56978d815d880.png)

+ 127
- 0
docs/Theme.md View File

@@ -0,0 +1,127 @@
**Theme configurations** consist of two parts: `menu` and `customize`:

## Menu
![Menu](https://ooo.0o0.ooo/2016/02/08/56b8797670b51.png)

Menus give you direct access to the archive, categories, custom pages, etc. You can create a menu simply by adding menu name and link address to the `menu` configuration section:

```diff
menu:
Home: .
Archives: archives
+ GitHub: https://github.com
```

> You can use both absolute addresses and relative addresses.

If you want enable the `Categories` and `Tags` for your blog, please copy `_source/categories` and `_source/tags` folder to `sources` folder under your site's root folder, and then add menu to your `_config.yml`.

```diff
menu:
Home: .
Archives: archives
+ Categories: categories
+ Tags: tags
```

## Customize
Customize configurations control the general appearance of your theme.

### Logo
You can replace the default logo with custom images. The `width` and `height` options define the size of the logo(in pixels), and `url` is the logo image file address. You can also hide the logo using `enabled: false`

```yaml
logo:
enabled: true
width: 165
height: 60
url: images/logo-header.png
```

> Don't add units to `width` and `height`, these options only support pure numbers.

> Please reserve `width`, `height` and `url` settings even when `enabled` is false.

### Profile
![Profile](https://ooo.0o0.ooo/2016/02/08/56b87cdd78cae.png)

Profile bar is the place to show a brief personal introduction of yours.

```yaml
profile:
enabled: true
avatar: css/images/avatar.png
gravatar:
author: PPOffice
author_title: Web Developer & Designer
location: Harbin, China
follow: https://github.com/ppoffice/
```

**enabled**: whether to show profile bar, options: true, false

**avatar**: path to your avatar image

**gavatar**: enter your Gravatar email address to enable Gavatar, this will override your avatar configuration

**author**: blogger name

**author_title**: a custom title

**location**: a custom location

**follow**: path to your homepage or something like that

### Highlight
![Highlight](https://ooo.0o0.ooo/2016/01/14/56973bf1680d1.png)

Icarus supports more than 60 code highlight themes imported from [Highlight.js](https://github.com/isagalaev/highlight.js). You can go to `icarus/source/css/_highlight` folder to see available options.

```diff
- highlight: androidstudio
+ highlight: tomorrow
```

### Sidebar
Change position of the sidebar. Available options are `left` and `right`.

```yaml
sidebar: left
```

### Thumbnail
Whether to enable thumbnail feature for each post. Available options are `true` and `false`.

```yaml
thumbnail: true
```

#### How to add a thumbnail to a post?
You can set your own thumbnail image by adding `banner` or `thumbnail` option in your post's [front-matter](https://hexo.io/docs/front-matter.html):

```diff
title: Hello World
date: 2013/7/13 20:46:25
+ thumbnail: https://example.com/image.jpg
---
```

### Favicon
Add a favicon for your site.

```yaml
favicon: favicon.png
```

### Social Links
![Social Links](https://ooo.0o0.ooo/2016/02/08/56b87c6be279f.png)

Show social links at the bottom of your profile bar. Add link name and link address in the `social_links` configuration and an [FontAwesome](http://fontawesome.io/) icon will be picked for you. Available social link options are listed [here](http://fontawesome.io/icons/#brand).

```diff
social_links:
github: https://github.com/ppoffice/hexo-theme-icarus
+ youtube: https://youtube.com
```

> Social links with empty link addresses will be omitted, so make sure you don't leave the addresses empty.

+ 28
- 0
docs/Widgets.md View File

@@ -0,0 +1,28 @@
Currently support widgets in Icarus:
```
widgets:
- recent_posts
- category
- archive
- tag
- tagcloud
- links
```

### Recent Posts
Show the latest 5 posts in your sidebar. Thumbnails can be disabled in the [Theme Configuration](https://github.com/ppoffice/hexo-theme-icarus/wiki/Theme#thumbnail).

### Category
Show categories in the sidebar.

### Archive
Show months of posts in the sidebar.

### Tag
Show tags in the sidebar.

### Tag Cloud
Show a tag cloud in the side bar.

### Links
Show custom links in the side bar. Links can be set in the [Miscellaneous Configurations](https://github.com/ppoffice/hexo-theme-icarus/wiki/Miscellaneous#links)

Loading…
Cancel
Save