This documentation will help you to understand Tranquilpeak Hugo theme code.
If you want to report a bug or ask a question, create an issue.
- General
- Requirements
- Installation
- Code style
- Code structure
- Views
- Assets
- NPM scripts
- Grunt tasks
- Tasks structure
- Pipeline
- Config tasks
- Register tasks
- Build
- Development environment
- Production environment (before deploying your blog)
- Running
- Author: Thibaud Leprêtre
- Version: 0.5.3-BETA (based on Hexo version 3.1.0)
- Compatibility: Hugo v0.53
- Hugo : v0.16 or higher, see official documentation (https://gohugo.io/overview/installing/)
- Grunt CLI : v0.1.13 or higher. Run
npm install grunt-cli -g
- Run
git clone https://github.com/kakawait/hugo-tranquilpeak-theme.git
- Rename the local folder from
hugo-tranquilpeak-theme
totranquilpeak
and place it inthemes
folder of your Hexo blog - Modify the hugo config in
config.toml
by changingtheme
variable totranquilpeak
- Go in
theme/tranquilpeak
folder withcd themes/tranquilpeak
- Install requirements
- Run
npm install
to install NPM dependencies
If you want to configure the theme, please follow the user documentation
We use ESLint based on Google code style to maintain javascript code style. Check code style with :
npm run lint
tranquilpeak
├── docs
├── layout
├── src
└── tasks
File/Folder | Description |
---|---|
docs | Contains user and developer documentation |
layout | Contains all views |
src | Contains all assets (css, js and images) |
tasks | Contains all grunt tasks |
├── layout
├── partials
│ ├── post
│ ...
...
...
Folder | Description |
---|---|
layout | Contails all mains views |
layout/partial | Contains all partial views included in main views |
layout/partial/post | Contains all partial views to build post |
SCSS structure follow 7-1 pattern of sass guidelines If you want more information and to understand better this code, consult sass guidelines
├── images
└── cover.jpg
File | Description |
---|---|
cover.png | Default background cover of the blog |
Contains all images of the theme.
├── 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
File | Description |
---|---|
about.js | Fade out the blog and let drop the about card of the author and vice versa |
archives-filter.js | Filter posts by using their date on archives page : /archives |
categories-filter.js | Filter posts by using their categories on archives page : /categories |
codeblock-resizer.js | Resize code blocks to fit the screen width |
fancybox.js.js | Run Fancybox plugin |
header.js | Hide the header when the user scrolls down, and show it when he scrolls up |
image-gallery.js | Resize all images of an image-gallery |
post-bottom-bar.js | Hide the post bottom bar when the post footer is visible by the user, and vice versa |
share-options.js | Open and close the share-options bar |
sidebar.js | Open and close the sidebar by swiping the sidebar and the blog and vice versa |
smartresize.js | Debouncing function from John Hann |
tabbed-codeblocks.js | Animate tabs of tabbed code blocks |
tags-filter.js | Filter posts by using their tags on archives page : /tags |
Each file correspond to a feature.
Use npm run <script_name>
to run one of these scripts. E.g : npm run start
npm run ... |
Description |
---|---|
start |
Build the theme once and rebuild after each change |
prod |
Build the theme for production. (synchronize images, fonts, compile assets (css and js) with some optimization (concat and minify) and link it to views) |
lint |
Check code style with ESLint |
├── tasks
├── config
├── register
└── pipeline.js
File/folder | Description |
---|---|
config | Default tasks |
register | Alias tasks which call multiple default tasks |
pipeline.js | Files which contains a list of javascript and stylesheets files linked to the blog |
// Js files to inject in `layout/partials/script.html`
var tranquilpeakJsFilesToInject = [
'jquery.js',
'jquery.fancybox.js',
'jquery.fancybox-thumbs.js',
'tranquilpeak.js'
];
// Css files to inject in `layout/partials/head.html`
var tranquilpeakCssFilesToInject = [
'font-awesome.css',
'jquery.fancybox.css',
'jquery.fancybox-thumbs.css',
'tranquilpeak.css'
];
Variable | Description |
---|---|
tranquilpeakJsFilesToInject | Files injected in layout/partials/script.html (development environment) |
tranquilpeakCssFilesToInject | Files injected inlayout/partials/head.html (development environment) |
On production environment, these javascript and stylesheets files are concatenate and minify in 1 javascript file and 1 stylesheet file and linked to their respective views
Task | Description |
---|---|
clean | Delete src/assets folder |
concat |
|
cssmin | Minify src/assets/cssstyle.css file in : src/assets/cssstyle.min.css |
exec |
|
sails-linker |
|
sass | Compile src/scss/tranquilpeak.scss file in src/assets/css/tranquilpeak.css |
sync | Synchronize images from src/images to src/assets/images and fonts from src/fonts to src/assets/fonts |
watch | Watch assets from src/*/**/* folder to detect changes and launch syncAssets task |
Task | Description |
---|---|
build | Synchronize images, fonts, compile assets (css and js) and link it to views |
buildProd | Synchronize images, fonts, compile assets (css and js) with some optimization (concat and minify) and link it to views |
default | Build the theme once and rebuild after each change |
eslint | Check code style with ESLint |
compileAssets | Compile scss files and concat js files |
linkAssets | Link all javascript and stylesheets files to views |
linkAssetsProd | Link one javascript file and one stylesheet file (concatenated and minified) to views |
syncAssets | Synchronize assets (css, js, fonts and images) |
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
- Run
npm run start
and start coding :)
- Run
npm run prod
to build the project with some optimization (concat and minify) to reduce number of HTTP requests and improve performance.
Run hugo server
and start coding! :)