jekyll-gitbook
layout: home title: Jekyll Gitbook Theme permalink: /
Make Jelly site have a GitBook look!
Demo
Live demo on Github Pages: https://sighingnow.github.io/jekyll-gitbook
Why Jekyll with GitBook
GitBook is an amazing frontend style to present and organize contents (such as book chapters
and blogs) on Web. The typical to deploy GitBook at Github Pages
is building HTML files locally and then push to Github repository, usually to the gh-pages
branch. It's quite annoying to repeat such workload and make it hard for people do version
control via git for when there are generated HTML files to be staged in and out.
This theme takes style definition out of generated GitBook site and provided the template for Jekyll to rendering markdown documents to HTML, thus the whole site can be deployed to Github Pages without generating and uploading HTML bundle every time when there are changes to the original repo.
How to Get Started
This theme can be used just as other Jekyll themes and support remote theme, see the official guide as well.
You can introduce this jekyll theme into your own site by either
- Fork this repository and add your markdown posts to the
_postsfolder. - Use as a remote theme in your
_config.yml(just like what we do for this site itself),
remote_theme: sighingnow/jekyll-gitbook
Deploy Locally with Jekyll Serve
This theme can be ran locally using Ruby and Gemfiles.
Testing your GitHub Pages site locally with Jekyll - GitHub
Full-text search
The search functionality in jekyll-gitbook theme is powered by the gitbook-plugin-search-pro plugin and is enabled by default.
https://sighingnow.github.io/jekyll-gitbook/?q=generated
Code highlight
The code highlight style is configurable the following entry in _config.yaml:
syntax_highlighter_style: colorful
The default code highlight style is colorful, the full supported styles can be found from the rouge repository. Customized
style can be added to ./assets/gitbook/rouge/.
How to generate TOC
The jekyll-gitbook theme leverages jekyll-toc to generate the Contents for the page.
The TOC feature is not enabled by default. To use the TOC feature, modify the TOC
configuration in _config.yml:
toc:
enabled: true
h_min: 1
h_max: 3
Google Analytics, etc.
The jekyll-gitboook theme supports embedding the Google Analytics, CNZZ and Application Insights website analytical tools with the following
minimal configuration in _config.yaml:
tracker:
google_analytics: "<YOUR GOOGLE ANALYTICS KEY, e.g, UA-xxxxxx-x>"
Similarly, CNZZ can be added with the following configuration in _config.yaml
tracker:
cnzz: "<YOUR CNZZ ANALYTICS KEY, e.g., xxxxxxxx>"
Application Insights can be added with the following configuration in _config.yaml
tracker:
application_insights: "<YOUR APPLICATION INSIGHTS CONNECTION STRING>"
Disqus comments
Disqus comments can be enabled by adding the following configuration in _config.yaml:
disqushandler: "<YOUR DISQUS SHORTNAME>"
Jekyll collections
Jekyll's collections is supported to organize the pages in a more fine-grained manner, e.g.,
collections:
pages:
output: true
sort_by: date
permalink: /:collection/:year-:month-:day-:title:output_ext
others:
output: true
sort_by: date
permalink: /:collection/:year-:month-:day-:title:output_ext
An optional ordered_collections key can be added to _config.yaml to control the order of collections in the sidebar:
ordered_collections:
- posts
- pages
- others
If not specified, the order of collections would be decided by Jekyll. Note that the key posts is a special collection
that indicates the _posts pages of Jekyll.
Extra StyleSheet or Javascript elements
You can add extra CSS or JavaScript references using configuration collections:
- extra_css: for additional style sheets. If the url does not start by http, the path must be relative to the root of the site, without a starting
/. - extra_header_js: for additional scripts to be included in the
<head>tag, after theextra_csshas been added. If the url does not start by http, the path must be relative to the root of the site, without a starting/. - extra_footer_js: for additional scripts to be included at the end of the HTML document, just before the site tracking script. If the url does not start by http, the path must be relative to the root of the site, without a starting
/.
Customizing font settings
The fonts can be customized by modifying the .book.font-family-0 and .book.font-family-1 entry in ./assets/gitbook/custom.css,
.book.font-family-0 {
font-family: Georgia, serif;
}
.book.font-family-1 {
font-family: "Helvetica Neue", Helvetica, Arial, sans-serif;
}
Tips, Warnings and Dangers blocks
The jekyll-gitbook theme supports customized kramdown attributes ({: .block-tip }, {: .block-warning },
{: .block-danger }) like that displayed in the discord.js website. The marker can be used like
> ##### TIP
>
> This guide is last tested with @napi-rs/canvas^0.1.20, so make sure you have
> this or a similar version after installation.
{: .block-tip }
Rendered page can be previewed from
https://sighingnow.github.io/jekyll-gitbook/jekyll/2022-06-30-tips_warnings_dangers.html
Cover image inside pages
The jekyll-gitbook theme supports adding a cover image to a specific page by adding
a cover field to the page metadata:
---
title: Page with cover image
author: Tao He
date: 2022-05-24
category: Jekyll
layout: post
+ cover: /assets/jekyll-gitbook/dinosaur.gif
---
The effect can be previewed from
https://sighingnow.github.io/jekyll-gitbook/jekyll/2022-05-24-page_cover.html
Diagrams with mermaid.js
This jekyll-theme supports mermaid.js to render diagrams in markdown.
To enable the mermaid support, you need to set mermaid: true in the front matter
of your post.
---
mermaid: true
---
The example can be previewed from
https://sighingnow.github.io/jekyll-gitbook/jekyll/2023-08-31-mermaid.html
License
This work is open sourced under the Apache License, Version 2.0.
Copyright 2019 Tao He.
