Jekyll Bootstrap

new post

2017-10-04T00:00:00+00:00

hcicmder python sample

2017-09-29T00:00:00+00:00

git_home\workspace\python\hcicmder\cmder1

jenkinsapi sphinx sample

use sphinx-quickstart

change conf.py

change theme setting inside conf.py

add autodoc inside conf.py

gn and ninja on windows

2017-09-28T00:00:00+00:00

why

build a system evolution

manual » script » makefile » auto-make » gn

adv: quick, small, tree-structure(makefile has)
disadv: it need all headers/libraries/source in side a package auto-make are created to use some uitiles to generate a makefile

reference: https://blog.simplypatrick.com/posts/2016/01-23-gn/

由於 GN 是用 C++ 撰寫，比起用 Python 寫的 GYP 快了將近 20 倍，GN 新的 DSL 的語法也被認為是比較好讀及維護的。

Usage

Use Steps

configure some args
Use gn to generate a build.ninja a inside ‘out’ folder
Use ninja to read build.ninja and do its work!

>mkdir out
>copy gn.args to out

>gn gen out
>ninja -C out

download ninja

https://github.com/ninja-build/ninja/releases

tutorial (https://ninja-build.org/manual.html#ref_rule)[https://ninja-build.org/manual.html#ref_rule]

download gn

gn is a tool to help build chrome browse in windows it is a part of source code inside chrome use git’s sha1 hash-value to download the file

cheat sheet

gn ls out
; see all the taregets
gn check out
; check target dependences
gn desc out <target>
; descript the detail of target
gn refs out <target>
; list parent-targets that refs to target
gn path out <target1> <target2>
; show all paths from target1 to targets

tutorial https://chromium.googlesource.com/chromium/src/+/lkgr/tools/gn/docs/quick_start.md

gn download tool https://github.com/cpu-chromium/gn_tool

download code

  with open(gn_path, 'wb') as f:
    f.write(urllib2.urlopen('https://chromium-gn.storage-download.googleapis.com/' + sha1).read())

gn help

J:\git_home\temp\fluoride_src\fluoride\bt>gn help

Commands (type "gn help <command>" for more help):
  analyze: Analyze which targets are affected by a list of files.
  args: Display or configure arguments declared by the build.
  check: Check header dependencies.
  clean: Cleans the output directory.
  desc: Show lots of insightful information about a target or config.
  format: Format .gn file.
  gen: Generate ninja files.
  help: Does what you think.
  ls: List matching targets.
  path: Find paths between two targets.
  refs: Find stuff referencing a target or file.

file format

gn use

variables: use ‘=’ to assign
rules: use a block (indent with spaces) to define

ninja_required_version = 1.3

#variable

cc = g++
cflags = -Wall

# rule
rule cc
    command = gcc $cflags -c $in -o $out
rule link
    command = gcc $cflags $in -o $out
build foo.o: cc foo.c
build 
build .exe: link foo.c

another example by me

use germ.c => germ.lib
use foo.c => foo.o
use foo.o + germ.lib => foo.exe

ninja_required_version = 1.3

#variable

cc = g++

cflags = -Wall

# rule

rule cc
    command = gcc $cflags -c $in -o $out
rule ar
    command = ar rcs $out $in
rule link
    command = gcc $in -o $out -lgerm -L.
#build foo.o: cc foo.c


build germ.o: cc germ.c
build foo.o: cc foo.c
build germ.lib: ar germ.o
build foo.exe: link foo.o

new post

2017-09-23T00:00:00+00:00

scapy

2017-09-19T00:00:00+00:00

scapy usage

Has the basic BT commands/packets encode/decode capability from scapy.layers.bluetooth import *

scapy-python3

use pyusb to send BT hci commands Try to do

Inquiry BR devices
Connect to a BR device
Get SDP data from a BR device
Connect a service of BR profiles
Inquiry LE devices
Connect to a LE device
Get a GATT service (any one)
Get a GATT data

20170919 progress: Add LE inquiry and set up event-filter

pybluetooth + scapy2

a LE inqury and connect sample

scapy-python2

Basic scapy sample

scapy-ironpython2

use c# to use winusb driver

pyqt5 sip swig callback

2017-09-18T00:00:00+00:00

swig

wxWidows(python) uses swig to communite with wxwidget(Clang)
PyQT(python) use its sip to commuite with QT (Clang)
python use builtin ctypes to do communicate with DLL files

swig vs sip

swig has tutorial sip only has a few articles in his document website Both generates PyObject to do the bridge between Clang and python

wxwidget sample

https://wiki.wxpython.org/C%2B%2BExtensions

swig sample at windows

http://falldog7.blogspot.tw/2013/07/python-swig-c-function.html

Bluetooth Stack for swig/sip

Thinking to use swig/sip with one of bluetooth stack on windows

BOSS - BLE only open source, embedded-type
BlueCove - java, profile-level, no-core
32feet - csharp, profile-level, no-core
btstack - dual, clang, use POSIX linux-path, embedded-type

swig for callback

both sip and swig doesn’t support callback direclty

%module test

%{
#include "test.hh"

class PyCallback
{
    PyObject *func;
    PyCallback& operator=(const PyCallback&); // Not allowed
public:
    PyCallback(const PyCallback& o) : func(o.func) {
      Py_XINCREF(func);
    }
    PyCallback(PyObject *func) : func(func) {
      Py_XINCREF(this->func);
      assert(PyCallable_Check(this->func));
    }
    ~PyCallback() {
      Py_XDECREF(func);
    }
    void operator()(const std::string& s) {
      if (!func || Py_None == func || !PyCallable_Check(func))
        return;
      PyObject *args = Py_BuildValue("(s)", s.c_str());
      PyObject *result = PyObject_Call(func,args,0);
      Py_DECREF(args);
      Py_XDECREF(result);
    }
};
%}

%include "test.hh"

%inline%{
  void register_handler(const QQEvent& e, PyObject *callback) {
    register_handler(e, PyCallback(callback));
  }
%}

Use sip pyqt5 to generate pyd

2017-09-16T00:00:00+00:00

Object - Use sip.exe of pyqt5 of windows to write a sample with mingw

python-to-clang extension

pyqt uses sip
wxwidget uses swig
kivy uses cython

Env

python –vesion Python 3.5.2
python -m pip -V pip 9.0.1 from c:\python35\lib\site-packages (python 3.5)
mingw64 **x64 ** x86_64-7.1.0-win32-seh-rt_v5-rev2
2015 visual studio (optional)
‘msvc’ MicroSoft Visual studio Compiler

Overview

2 way to build pyd

configure way: split origin library and generate pyd
setup way: build and generate pyd in setup.py script
Same as configure way. but it builds libword.a in setup.py

mingw normal usage

C:\mingw64>mingw-w64

PATH c:\mingw64\mingw64\bin;

Has native tools

mingw32-make
gcc.exe
g++.exe

**Caution!**
mingw uses dos filepath, not unix-like filepath
msys uses unix-like filepath
cygwin uses unix-like filepath

mingw build static library

use g++ to compile object files use ar to compile static library

https://www.codeproject.com/Articles/84461/MinGW-Static-and-Dynamic-Libraries

Compiling the static library

>gcc -c add.c -o add.o
>ar rcs libadd.a add.o

compiling the dynamic library

gcc -c add.c -o add.o
gcc -shared -o libadd.so add.o
gcc -o main.exe main.c libadd.so

PyQt4 sip sample tutorial

pyqt4 sample - Error run with pyqt5 ! no sipconfig ! no sipdistutils

ImportError: No module named ‘sipconfig’ change to sipdistutils. Still failed

BOTH are Not longer support at PyQt5 and sip5 further

http://pyqt.sourceforge.net/Docs/sip4/using.html

solution!

download sip source and generate win32-g++ or msvc sipconfig.py
copy sipconfig.py and sipdistutils.py to project folder

How to get sipconfig.py for configure.py

We need to generate it from sip source code

sipconfig.py is used to generate a Makefile

  >python configure.py --platform win32-g++
  or
  >python configure.py --platform msvc

How to get sipdistutils.py for setup.py

sipdistutils.py is exists inside sip source code

sipdistutils.py is used by distutil module / setup.py of python

discussion https://github.com/wbsoft/python-poppler-qt5/issues/14
download url https://www.riverbankcomputing.com/hg/sip/file/14685a6e736e/sipdistutils.py
setup.py not found gcc change to use msvc
setup.py not found sipconfig.py copy sip source’s sipconfig.py to local
setup.py can not find the sip.h and sip.exe change sipconfig.py setting https://docs.python.org/2/distutils/setupscript.html
cannot find word.h/word.cpp add include_dirs to setup.py Extension(“word”, [“word.sip”, “word.cpp”], include_dirs=[’.’, ]), ],
build pass but run-time error. assert at sip.dll

Get spiconfig.py from sip ssurce code

Get spiconfig.py from sip_src.zip’s configure.y

generate a mingw64 vesrion sipconfig.py

python configure.py --platform win32-g++

generate a vs2015 version sipconfig.py

python configure.py --platform msvc

if you don’t want to pass ‘–platform wn32-g++’ to python distutil module

C:\python35\Lib\distutils\distutils.cfg

[build]
compiler=msvc

Fix Makefile from ‘python configure.py’

Use “python configure.py” to generate Makefile

the default Makefile has some bugs

 >/Library/mingw-w64/lib/gcc/x86_64-w64-mingw32/7.1.0/include/c++/cmath:1136:11: error: '::hypot' has not been declared
               using ::hypot;
        
                       ^~~~~
        I found a solution at
        `g++ error on import of Theano on Windows 7 <https://stackoverflow.com/questions/38536788/g-error-on-import-of-theano-on-windows-7>`_.

        The solution is to create a file in the user folder called ``.theanorc`` which contains:
        ::
            [gcc]
            cxxflags = -D_hypot=hypot

g++ -mthreads -Wl,-enable-stdcall-fixup -Wl,-enable-auto-import -Wl,-enable-runtime-pseudo-reloc -shared -Wl,-subsystem,windows -Wl,-s -o word.pyd sipwordcmodule.o sipwordWord.o -Lc:\python35\libs -lword -lpython35 -L.
c:/mingw64/mingw64/bin/../lib/gcc/x86_64-w64-mingw32/7.1.0/../../../../x86_64-w64-mingw32/bin/ld.exe: cannot find -lword
collect2.exe: error: ld returned 1 exit status
mingw32-make: *** [Makefile:36: word.pyd] Error 1

python setup.py bdist screenshot

running bdist
running bdist_dumb
running build
running build_ext
installing to build\bdist.win-amd64\dumb
running install
running install_lib
creating build\bdist.win-amd64
creating build\bdist.win-amd64\dumb
creating build\bdist.win-amd64\dumb\python35
creating build\bdist.win-amd64\dumb\python35\Lib
creating build\bdist.win-amd64\dumb\python35\Lib\site-packages
copying build\lib.win-amd64-3.5\word.cp35-win_amd64.pyd -> build\bdist.win-amd64\dumb\python35\Lib\site-packages
running install_egg_info
Writing build\bdist.win-amd64\dumb\python35\Lib\site-packages\word-0.0.0-py3.5.egg-info
creating J:\git_home\workspace\qt\siptest\sip_tutorial1\dist
creating 'J:\git_home\workspace\qt\siptest\sip_tutorial1\dist\word-0.0.0.win-amd64.zip' and adding '.' to it
adding 'python35\Lib\site-packages\word-0.0.0-py3.5.egg-info'
adding 'python35\Lib\site-packages\word.cp35-win_amd64.pyd'
removing 'build\bdist.win-amd64\dumb' (and everything under it)

c:\python35\lib\distutils\dist.py:261: UserWarning: Unknown distribution option: 'versione'
  warnings.warn(msg)
running install
running build
running build_ext
running install_lib
copying build\lib.win-amd64-3.5\word.cp35-win_amd64.pyd -> c:\python35\Lib\site-packages
running install_egg_info
Writing c:\python35\Lib\site-packages\word-0.0.0-py3.5.egg-info

btstack compiled on windows with msys

2017-09-14T00:00:00+00:00

Official resource

github https://github.com/bluekitchen/btstack

manuual http://bluekitchen-gmbh.com/btstack/

License

Commercial !!!

Install

follow the installation instructions at ‘manual’

install python, msys2 (POSIX command line), mingw64 (gcc), git, winpty

To install with MSYS2 : pacman -S mingw-w64-x86_64-gcc
To install with unzip : pacman -S unzip
To install with git   : pacman -S git
To install with winpty: pacman -S winpty

compiling-the-example

Modify Makeifle

Use ~/git_home/btstack/port/windows-winusb as sample

Modify ~/git_home/btstack/port/windows-winusb/Makefile

Example=lecounter hfp_hf_demo

Example=lecounter hfp_hf_demo gap_inquiry

Run sample

winpty ./gap_inquiry.exe

Inquiry near bluetooth devices

winpty ./hfp_hf_demo.exe

Use a phone as hfp ag and connect to this demo

Press ‘X’ or ‘W’ in winpty console to show-status or do redial action

Architecture

sikuli automation test

2017-09-09T00:00:00+00:00

sikuli

用java + python 寫出的graphic script language

offical url

http://www.sikuli.org/

tutorial

https://www.techbang.com/posts/1907-drawings-to-write-programs-sikuli-will-change-the-world?comment_page=2#comments-list

強制中止的話要按alt+shift+c

開發過程

想要一個script, 一直監看左方螢幕有X 時, 去關掉視窗
找到region 說明. http://doc.sikuli.org/region.html
看不懂. 找了sample. 還是不懂
看說明跟debug 方式. 圖上有show & show-in, 分別可以在cursor現在後面圖去做比對的動作
先抓一個X, 命名為ps(如下圖). 然後按下show 按鈕. 發現畫面左邊一點才可以match
發現會抓到後, 但若馬上畫面上沒有x, 就會timeout而failed. 找’find forever sikuli’
改搜尋wait() 不timeout 的設定. 原來要另外setAutoWaitTimeout(), 或是find(, timeout) 要設定第二個參數. 沒有forever

參考

sample1 https://kkboxsqa.wordpress.com/2014/04/21/ui-%E8%87%AA%E5%8B%95%E5%8C%96%E6%B8%AC%E8%A9%A6%E4%BD%BF%E7%94%A8-sikuli-%E6%93%8D%E4%BD%9C%E4%BB%8B%E7%B4%B9-part-2/
sample2 https://answers.launchpad.net/sikuli/+question/206657

sikulix at android - ankulua

現在可以直接在Android 上面使用Sikuli 了 AnkuLua = Android + Sikuli + Lua 我們是AnkuLua 開發者歡迎試用介紹並給我們指教

按鍵精靈

https://read01.com/Ay4RJo.html#.WbP0JcgjGUk

TOEIC

2017-09-06T00:00:00+00:00

Resource

Exam Types

TOEIC
TOEIC SW (speak and writing)
[TOEIC cert level] (http://cle.nkfust.edu.tw/ezfiles/123/1123/img/1825/165972056.pdf)

Resource

backgound

一年台灣5000考平均分數 550 考一次$1500 考150 分鐘 (2.5hr) 可以上廁所, 手機要靜音, 不然考試無效

exam

how to use jekyll

2017-09-05T00:00:00+00:00

New a post

>rake post

New a page

>rake page

Local preview and watch changes

>jekyll server --watch

Build changes to _sites folder

>jekyll build

jekyll usage

2017-09-04T00:00:00+00:00

tutorial & sample

jekyll_usage

jekyll-sample

Jekyll Introduction

2011-12-29T00:00:00+00:00

This Jekyll introduction will outline specifically what Jekyll is and why you would want to use it. Directly following the intro we’ll learn exactly how Jekyll does what it does.

Overview

What is Jekyll?

Jekyll is a parsing engine bundled as a ruby gem used to build static websites from dynamic components such as templates, partials, liquid code, markdown, etc. Jekyll is known as “a simple, blog aware, static site generator”.

Examples

This website is created with Jekyll. Other Jekyll websites.

What does Jekyll Do?

Jekyll is a ruby gem you install on your local system. Once there you can call jekyll --server on a directory and provided that directory is setup in a way jekyll expects, it will do magic stuff like parse markdown/textile files, compute categories, tags, permalinks, and construct your pages from layout templates and partials.

Once parsed, Jekyll stores the result in a self-contained static _site folder. The intention here is that you can serve all contents in this folder statically from a plain static web-server.

You can think of Jekyll as a normalish dynamic blog but rather than parsing content, templates, and tags on each request, Jekyll does this once beforehand and caches the entire website in a folder for serving statically.

Jekyll is Not Blogging Software

Jekyll is a parsing engine.

Jekyll does not come with any content nor does it have any templates or design elements. This is a common source of confusion when getting started. Jekyll does not come with anything you actually use or see on your website - you have to make it.

Why Should I Care?

Jekyll is very minimalistic and very efficient. The most important thing to realize about Jekyll is that it creates a static representation of your website requiring only a static web-server. Traditional dynamic blogs like Wordpress require a database and server-side code. Heavily trafficked dynamic blogs must employ a caching layer that ultimately performs the same job Jekyll sets out to do; serve static content.

Therefore if you like to keep things simple and you prefer the command-line over an admin panel UI then give Jekyll a try.

Developers like Jekyll because we can write content like we write code:

Ability to write content in markdown or textile in your favorite text-editor.
Ability to write and preview your content via localhost.
No internet connection required.
Ability to publish via git.
Ability to host your blog on a static web-server.
Ability to host freely on GitHub Pages.
No database required.

How Jekyll Works

The following is a complete but concise outline of exactly how Jekyll works.

Be aware that core concepts are introduced in rapid succession without code examples. This information is not intended to specifically teach you how to do anything, rather it is intended to give you the full picture relative to what is going on in Jekyll-world.

Learning these core concepts should help you avoid common frustrations and ultimately help you better understand the code examples contained throughout Jekyll-Bootstrap.

Initial Setup

After installing jekyll you’ll need to format your website directory in a way jekyll expects. Jekyll-bootstrap conveniently provides the base directory format.

The Jekyll Application Base Format

Jekyll expects your website directory to be laid out like so:

.
|-- _config.yml
|-- _includes
|-- _layouts
|   |-- default.html
|   |-- post.html
|-- _posts
|   |-- 2011-10-25-open-source-is-good.markdown
|   |-- 2011-04-26-hello-world.markdown
|-- _site
|-- index.html
|-- assets
    |-- css
        |-- style.css
    |-- javascripts

_config.yml Stores configuration data.
_includes This folder is for partial views.
_layouts This folder is for the main templates your content will be inserted into. You can have different layouts for different pages or page sections.
_posts This folder contains your dynamic content/posts. the naming format is required to be @YEAR-MONTH-DATE-title.MARKUP@.
_site This is where the generated site will be placed once Jekyll is done transforming it.
assets This folder is not part of the standard jekyll structure. The assets folder represents any generic folder you happen to create in your root directory. Directories and files not properly formatted for jekyll will be left untouched for you to serve normally.

Jekyll Configuration

Jekyll supports various configuration options that are fully outlined here: (https://github.com/mojombo/jekyll/wiki/Configuration)

Content in Jekyll

Content in Jekyll is either a post or a page. These content “objects” get inserted into one or more templates to build the final output for its respective static-page.

Posts and Pages

Both posts and pages should be written in markdown, textile, or HTML and may also contain Liquid templating syntax. Both posts and pages can have meta-data assigned on a per-page basis such as title, url path, as well as arbitrary custom meta-data.

Working With Posts

Creating a Post Posts are created by properly formatting a file and placing it the _posts folder.

Formatting A post must have a valid filename in the form YEAR-MONTH-DATE-title.MARKUP and be placed in the _posts directory. If the data format is invalid Jekyll will not recognize the file as a post. The date and title are automatically parsed from the filename of the post file. Additionally, each file must have YAML Front-Matter prepended to its content. YAML Front-Matter is a valid YAML syntax specifying meta-data for the given file.

Order Ordering is an important part of Jekyll but it is hard to specify a custom ordering strategy. Only reverse chronological and chronological ordering is supported in Jekyll.

Since the date is hard-coded into the filename format, to change the order, you must change the dates in the filenames.

Tags Posts can have tags associated with them as part of their meta-data. Tags may be placed on posts by providing them in the post’s YAML front matter. You have access to the post-specific tags in the templates. These tags also get added to the sitewide collection.

Categories Posts may be categorized by providing one or more categories in the YAML front matter. Categories offer more significance over tags in that they can be reflected in the URL path to the given post. Note categories in Jekyll work in a specific way. If you define more than one category you are defining a category hierarchy “set”. Example:

---
title :  Hello World
categories : [lessons, beginner]
---

This defines the category hierarchy “lessons/beginner”. Note this is one category node in Jekyll. You won’t find “lessons” and “beginner” as two separate categories unless you define them elsewhere as singular categories.

Working With Pages

Creating a Page Pages are created by properly formatting a file and placing it anywhere in the root directory or subdirectories that do not start with an underscore.

Formatting In order to register as a Jekyll page the file must contain YAML Front-Matter. Registering a page means 1) that Jekyll will process the page and 2) that the page object will be available in the site.pages array for inclusion into your templates.

Categories and Tags Pages do not compute categories nor tags so defining them will have no effect.

Sub-Directories If pages are defined in sub-directories, the path to the page will be reflected in the url. Example:

.
|-- people
    |-- bob
        |-- essay.html

This page will be available at http://yourdomain.com/people/bob/essay.html

Recommended Pages

index.html You will always want to define the root index.html page as this will display on your root URL.
404.html Create a root 404.html page and GitHub Pages will serve it as your 404 response.
sitemap.html Generating a sitemap is good practice for SEO.
about.html A nice about page is easy to do and gives the human perspective to your website.

Templates in Jekyll

Templates are used to contain a page’s or post’s content. All templates have access to a global site object variable: site as well as a page object variable: page. The site variable holds all accessible content and metadata relative to the site. The page variable holds accessible data for the given page or post being rendered at that point.

Create a Template Templates are created by properly formatting a file and placing it in the _layouts directory.

Formatting Templates should be coded in HTML and contain YAML Front Matter. All templates can contain Liquid code to work with your site’s data.

Rending Page/Post Content in a Template There is a special variable in all templates named : content. The content variable holds the page/post content including any sub-template content previously defined. Render the content variable wherever you want your main content to be injected into your template:

...
<body>
  <div id="sidebar"> ... </div>
  <div id="main">
    {{content}}
  </div>
</body>
...

Sub-Templates

Sub-templates are exactly templates with the only difference being they define another “root” layout/template within their YAML Front Matter. This essentially means a template will render inside of another template.

Includes

In Jekyll you can define include files by placing them in the _includes folder. Includes are NOT templates, rather they are just code snippets that get included into templates. In this way, you can treat the code inside includes as if it was native to the parent template.

Any valid template code may be used in includes.

Using Liquid for Templating

Templating is perhaps the most confusing and frustrating part of Jekyll. This is mainly due to the fact that Jekyll templates must use the Liquid Templating Language.

What is Liquid?

Liquid is a secure templating language developed by Shopify. Liquid is designed for end-users to be able to execute logic within template files without imposing any security risk on the hosting server.

Jekyll uses Liquid to generate the post content within the final page layout structure and as the primary interface for working with your site and post/page data.

Why Do We Have to Use Liquid?

GitHub uses Jekyll to power GitHub Pages. GitHub cannot afford to run arbitrary code on their servers so they lock developers down via Liquid.

Liquid is Not Programmer-Friendly.

The short story is liquid is not real code and its not intended to execute real code. The point being you can’t do jackshit in liquid that hasn’t been allowed explicitly by the implementation. What’s more you can only access data-structures that have been explicitly passed to the template.

In Jekyll’s case it is not possible to alter what is passed to Liquid without hacking the gem or running custom plugins. Both of which cannot be supported by GitHub Pages.

As a programmer - this is very frustrating.

But rather than look a gift horse in the mouth we are going to suck it up and view it as an opportunity to work around limitations and adopt client-side solutions when possible.

Aside My personal stance is to not invest time trying to hack liquid. It’s really unnecessary from a programmer’s perspective. That is to say if you have the ability to run custom plugins (i.e. run arbitrary ruby code) you are better off sticking with ruby. Toward that end I’ve built Mustache-with-Jekyll

Static Assets

Static assets are any file in the root or non-underscored subfolders that are not pages. That is they have no valid YAML Front Matter and are thus not treated as Jekyll Pages.

Static assets should be used for images, css, and javascript files.

How Jekyll Parses Files

Remember Jekyll is a processing engine. There are two main types of parsing in Jekyll.

Content parsing. This is done with textile or markdown.
Template parsing. This is done with the liquid templating language.

And thus there are two main types of file formats needed for this parsing.

Post and Page files. All content in Jekyll is either a post or a page so valid posts and pages are parsed with markdown or textile.
Template files. These files go in _layouts folder and contain your blogs templates. They should be made in HTML with the help of Liquid syntax. Since include files are simply injected into templates they are essentially parsed as if they were native to the template.

Arbitrary files and folders. Files that are not valid pages are treated as static content and pass through Jekyll untouched and reside on your blog in the exact structure and format they originally existed in.

Formatting Files for Parsing.

We’ve outlined the need for valid formatting using YAML Front Matter. Templates, posts, and pages all need to provide valid YAML Front Matter even if the Matter is empty. This is the only way Jekyll knows you want the file processed.

YAML Front Matter must be prepended to the top of template/post/page files:

---
layout: post
category : pages
tags : [how-to, jekyll]
---

... contents ...

Three hyphens on a new line start the Front-Matter block and three hyphens on a new line end the block. The data inside the block must be valid YAML.

Configuration parameters for YAML Front-Matter is outlined here: A comprehensive explanation of YAML Front Matter

Defining Layouts for Posts and Templates Parsing.

The layout parameter in the YAML Front Matter defines the template file for which the given post or template should be injected into. If a template file specifies its own layout, it is effectively being used as a sub-template. That is to say loading a post file into a template file that refers to another template file with work in the way you’d expect; as a nested sub-template.

How Jekyll Generates the Final Static Files.

Ultimately, Jekyll’s job is to generate a static representation of your website. The following is an outline of how that’s done:

Jekyll collects data. Jekyll scans the posts directory and collects all posts files as post objects. It then scans the layout assets and collects those and finally scans other directories in search of pages.
Jekyll computes data. Jekyll takes these objects, computes metadata (permalinks, tags, categories, titles, dates) from them and constructs one big site object that holds all the posts, pages, layouts, and respective metadata. At this stage your site is one big computed ruby object.
Jekyll liquifies posts and templates. Next jekyll loops through each post file and converts (through markdown or textile) and liquifies the post inside of its respective layout(s). Once the post is parsed and liquified inside the the proper layout structure, the layout itself is “liquified”. Liquification is defined as follows: Jekyll initiates a Liquid template, and passes a simpler hash representation of the ruby site object as well as a simpler hash representation of the ruby post object. These simplified data structures are what you have access to in the templates.
Jekyll generates output. Finally the liquid templates are “rendered”, thereby processing any liquid syntax provided in the templates and saving the final, static representation of the file.

Notes. Because Jekyll computes the entire site in one fell swoop, each template is given access to a global site hash that contains useful data. It is this data that you’ll iterate through and format using the Liquid tags and filters in order to render it onto a given page.

Remember, in Jekyll you are an end-user. Your API has only two components:

The manner in which you setup your directory.
The liquid syntax and variables passed into the liquid templates.

All the data objects available to you in the templates via Liquid are outlined in the API Section of Jekyll-Bootstrap. You can also read the original documentation here: https://github.com/mojombo/jekyll/wiki/Template-Data

Conclusion

I hope this paints a clearer picture of what Jekyll is doing and why it works the way it does. As noted, our main programming constraint is the fact that our API is limited to what is accessible via Liquid and Liquid only.

Jekyll-bootstrap is intended to provide helper methods and strategies aimed at making it more intuitive and easier to work with Jekyll =)

Thank you for reading this far.

Next Steps

Please take a look at or jump right into Usage if you’d like.