Next revision | Previous revision |
blogging_with_jekyll [2021/03/22 21:37] – created hc9 | blogging_with_jekyll [2021/03/22 21:46] (current) – [Post template] hc9 |
---|
====== Blogging with Jekyll ====== | ====== Blogging with Jekyll ====== |
| |
| ===== Introduction ===== |
| |
From the [[http://wiki.github.com/mojombo/jekyll|Jekyll wiki]]: | From the [[http://wiki.github.com/mojombo/jekyll|Jekyll wiki]]: |
> ''destination: /absolute/path/to/html/motd'' | > ''destination: /absolute/path/to/html/motd'' |
| |
Replace "/absolute/path/to" with the path to your home directory. Type "echo $HOME" in the shell if you're unsure. | Replace ''/absolute/path/to'' with the path to your home directory. Type ''echo $HOME'' in the shell if you're unsure. |
| |
===== Using the Liquid templating engine ===== | ===== Using the Liquid templating engine ===== |
==== Output markup ==== | ==== Output markup ==== |
| |
Output markup is fairly simple. The basic format is ''<nowiki>{{</nowiki> variable | filter <nowiki>}}</nowiki>''. The variables are typically built into Jekyll, so one usually doesn't have to worry about declaring them. ''site'' is a variable that stores site-wide information in sub-variables. For example, ''site.posts'' is a list of all the site's posts. Each post has its own "post" variable, which includes information such as ''post.title'', ''post.url'', and "post.date" Another important variable is "content", which is used in templates to denote where the content will be inserted. A complete list of template data can be found [[http://wiki.github.com/mojombo/jekyll/template-data|here]]. Filters are used to manipulate theoutput of variables. When a filter is not specified (''<nowiki>{{</nowiki> variable <nowiki>}}</nowiki>''), the variable is simply printed. Liquid has a bunch of built-in filters that can be found, along with a whole summary of using Liquid, [[http://wiki.github.com/tobi/liquid/liquid-for-designers|here]]. Jekyll also has some of its own filters, such as ''number_of_words'' and ''array_to_sentence_string'', which turns an array variable into a list of words separated by commas and an "and." The complete list can be found [[http://wiki.github.com/mojombo/jekyll/liquid-extensions| here]], along with Jekyll's extra tags. | Output markup is fairly simple. The basic format is ''<nowiki>{{</nowiki> variable | filter <nowiki>}}</nowiki>''. The variables are typically built into Jekyll, so one usually doesn't have to worry about declaring them. ''site'' is a variable that stores site-wide information in sub-variables. For example, ''site.posts'' is a list of all the site's posts. Each post has its own ''post'' variable, which includes information such as ''post.title'', ''post.url'', and ''post.date'' Another important variable is ''content'', which is used in templates to denote where the content will be inserted. A complete list of template data can be found [[http://wiki.github.com/mojombo/jekyll/template-data|here]]. Filters are used to manipulate theoutput of variables. When a filter is not specified (''<nowiki>{{</nowiki> variable <nowiki>}}</nowiki>''), the variable is simply printed. Liquid has a bunch of built-in filters that can be found, along with a whole summary of using Liquid, [[http://wiki.github.com/tobi/liquid/liquid-for-designers|here]]. Jekyll also has some of its own filters, such as ''number_of_words'' and ''array_to_sentence_string'', which turns an array variable into a list of words separated by commas and an "and." The complete list can be found [[http://wiki.github.com/mojombo/jekyll/liquid-extensions| here]], along with Jekyll's extra tags. |
| |
==== Tag markup ==== | ==== Tag markup ==== |
==== Post template ==== | ==== Post template ==== |
| |
''post.html'' determines the layout for post pages. Here we first encounter YAML front matter. YAML stands for "YAML Ain't a Markup Language," Any YAML content is placed between ''<nowiki>---</nowiki>'' and ''<nowiki>---</nowiki>'' (each on their own line) at the beginning of a document. In this front matter we can set variables in the format, "variable: value". The only variable we need to set for the post template is "layout: default". This tells Jekyll to insert this template into ''<nowiki>{{</nowiki> content <nowiki>}}</nowiki>'' in the default layout. We'll also want to add a ''<nowiki>{{</nowiki> content <nowiki>}}</nowiki>'' to the post template. This is where the actual post will get inserted. We also might want to add somethings like ''<nowiki>{{</nowiki> page.title <nowiki>}}</nowiki>'' and ''<nowiki>{{</nowiki> page.date | date: "%A %d %B %Y" <nowiki>}}</nowiki>'', which will format the post's date as ''Weekday Day Month Year''. | ''post.html'' determines the layout for post pages. Here we first encounter YAML front matter. YAML stands for "YAML Ain't a Markup Language," Any YAML content is placed between ''<nowiki>---</nowiki>'' and ''<nowiki>---</nowiki>'' (each on their own line) at the beginning of a document. In this front matter we can set variables in the format, ''variable: value''. The only variable we need to set for the post template is ''layout: default''. This tells Jekyll to insert this template into ''<nowiki>{{</nowiki> content <nowiki>}}</nowiki>'' in the default layout. We'll also want to add a ''<nowiki>{{</nowiki> content <nowiki>}}</nowiki>'' to the post template. This is where the actual post will get inserted. We also might want to add somethings like ''<nowiki>{{</nowiki> page.title <nowiki>}}</nowiki>'' and ''<nowiki>{{</nowiki> page.date | date: "%A %d %B %Y" <nowiki>}}</nowiki>'', which will format the post's date as ''Weekday Day Month Year''. |
| |
==== Other templates ==== | ==== Other templates ==== |
===== Creating the index page ===== | ===== Creating the index page ===== |
| |
The web site will of course need an index page, "index.html". As usual, this will get interpreted by Liquid. But first we'll need to add the front matter. The layout should probably be default again. If any of the layouts use ''<nowiki>{{</nowiki> page.title <nowiki>}}</nowiki>'', we can define the title of the home page now with ''title: This Is My Title''. After the YAML front matter, we'll probably want a list of the posts. This can be done with a for loop: ''{% for post in site.posts %}''. Format the HTML content inside the loop in any way, maybe using ''<nowiki>{{</nowiki> post.date <nowiki>}}</nowiki>'' and ''<nowiki>{{</nowiki> post.title <nowiki>}}</nowiki>''. | The web site will of course need an index page, ''index.html''. As usual, this will get interpreted by Liquid. But first we'll need to add the front matter. The layout should probably be default again. If any of the layouts use ''<nowiki>{{</nowiki> page.title <nowiki>}}</nowiki>'', we can define the title of the home page now with ''title: This Is My Title''. After the YAML front matter, we'll probably want a list of the posts. This can be done with a for loop: ''{% for post in site.posts %}''. Format the HTML content inside the loop in any way, maybe using ''<nowiki>{{</nowiki> post.date <nowiki>}}</nowiki>'' and ''<nowiki>{{</nowiki> post.title <nowiki>}}</nowiki>''. |
| |
===== Writing a post ===== | ===== Writing a post ===== |