Paporubio developer documentation

This documentation will help you to understand Tranquilpeak Hexo theme code.

If you want to report a bug or ask a question, create an issue.

Summary

• General
• Requirements
• Installation
• Code style
• Code structure
  • Languages
  • Views
  • Scripts
  • Assets
    • Stylesheets
    • Fonts
    • Images
    • Javascript
• NPM scripts
• Grunt tasks
  • Tasks structure
  • Pipeline
  • Config tasks
  • Register tasks
• Build
• Running

General

• Author : Louis Barranqueiro
• Version : 1.10.0
• Compatibility : Node v4 or later, Hexo v3.0.0 or later

Requirements

1. Node : v4 or higher. Download Node
2. Hexo CLI : v0.1.4 or higher. Run npm install hexo-cli -g
3. Grunt CLI : v0.1.13 or higher. Run npm install grunt-cli -g
4. Bower : v1.4.1 or higher. Run npm install bower -g

Installation

1. Run git clone https://github.com/LouisBarranqueiro/hexo-theme-tranquilpeak.git
2. Rename the folder in tranquilpeak and place it in themes folder of your Hexo blog
3. Modify the theme in _config.yml by changing theme variable to tranquilpeak
4. Complete theme/tranquilpeak/_config.yml with your information by following directives in comments
5. Go in theme/tranquilpeak folder with cd themes/tranquilpeak
6. Install requirements
7. Run npm install to install NPM dependencies
8. Run bower install to install Bower dependencies

If you want to configure the theme, please follow the user documentation

Code style

We use ESLint based on Google code style to maintain javascript code style.
Check code style with :

npm run lint
# or
grunt eslint

Code structure

tranquilpeak
├── .github
├── docs
├── languages
├── layout
├── scripts
├── source
└── tasks

Languages

Each file contains all the labels used in the theme.
If you want to add a new language, duplicate an existing language file and replace every string with their translation.

Views

├── layout
    ├── _partial
    │   ├── post
    │   ...
    ...
...

Scripts

├── scripts
    ├── filters
    ├── helpers
    ├── migrators
    └── tags

Each script is executed at the startup of Hexo. They are separated by categories:

Assets

Stylesheets

SCSS structure follow 7-1 pattern of sass guidelines
If you want more information to better understand this code, consult sass guidelines

Fonts

├── _fonts
    └── .gitkeep

If you have local fonts, place them in this folder and import them in source/_css/utils/_fonts.scss.

Images

├── _images
    └── cover.jpg

Contains all images of the theme.

Javascript

├── _js
    ├── .eslintrc.json
    ├── about.js
    ├── archives-filter.js
    ├── categories-filter.js
    ├── codeblock-resizer.js
    ├── fancybox.js
    ├── header.js
    ├── image-gallery.js
    ├── post-bottom-bar.js
    ├── share-options.js
    ├── sidebar.js
    ├── smartresize.js
    ├── tabbed-codeblocks.js
    └── tags-filter.js

Each file correspond to a feature.

NPM scripts

Use npm run <script_name> to run one of these scripts. E.g : npm run start

Grunt tasks

Tasks structure

├── tasks
    ├── config
    ├── register
    └── pipeline.js

Pipeline

// Js files to inject in `layout/_partial/script.ejs`
var tranquilpeakJsFilesToInject = [
    'jquery.js',
    'jquery.fancybox.js',
    'jquery.fancybox-thumbs.js',
    'tranquilpeak.js'
];
// Css files to inject in `layout/_partial/head.ejs`
var tranquilpeakCssFilesToInject = [
    'font-awesome.css',
    'jquery.fancybox.css',
    'jquery.fancybox-thumbs.css',
    'tranquilpeak.css'
];

In the production environment, these javascript and stylesheets files are concatenated and minified into 1 javascript file and 1 stylesheet file and linked to their respective views.

Config tasks

Register tasks

When you run grunt build or grunt buildProd tasks, a source/assets folder will be created with all files generated in. When you will start your hexo server, only this folder will be copied in public folder

Build

Development environment

1. Run npm run start or grunt default and start coding :)

Production environment (before deploying your blog)

1. Run npm run prod or grunt buildProd to build the project with some optimization (concat and minify) to reduce number of HTTP requests and improve performance.

Running

Run hexo server and start coding! :)