├── DATE.md ├── FAQ.md ├── GITHUB.md ├── JEKYLL.md ├── OCTOPRESS.md ├── README.md ├── WORDPRESS.md ├── YAML.md └── notes ├── JEKYLL.md └── YAML.md /DATE.md: -------------------------------------------------------------------------------- 1 | 2 | Work-In-Progess 3 | 4 | # Working with Dates and Times 5 | 6 | ## Formatting 7 | 8 | Formatting Examples 9 | ~~~ 10 | {{ post.date | date: "%B %-d, %Y" } => 11 | ~~~ 12 | 13 | 14 | 15 | ## Sort, Filter 16 | 17 | Add sample - sort posts / collection pages by year 18 | 19 | 20 | ~~~ 21 | ~~~ 22 | 23 | 24 | 25 | ## Time Zones 26 | 27 | add notes about time zones 28 | -------------------------------------------------------------------------------- /FAQ.md: -------------------------------------------------------------------------------- 1 | # Jekyll F.A.Q.s - Frequently Asked Questions (and Answers) 2 | 3 | [What's News?](#whats-news) • 4 | [Themes / Templates](#themes--templates) • 5 | [Getting Help](#getting-help) • 6 | [Troubleshooting](#troubleshooting) • 7 | [GitHub Pages](#github-pages) • 8 | [History / Trivia](#history--trivia) • 9 | [Meta](#meta) 10 | 11 | 12 | 13 | ## What's News? 14 | 15 | #### Q: Where can I find the latest (and greatest) Jekyll news and goodies? 16 | 17 | Check the official Jekyll news blog (web: [jekyllrb.com/news](http://jekyllrb.com/news)) 18 | or the Twitter page (t: [jekyllrb](https://twitter.com/jekyllrb)). 19 | 20 | For detailed upcoming major and minor enhancements and bug fixes, see the [History page](https://github.com/jekyll/jekyll/blob/master/History.markdown) in the Jekyll repo. 21 | 22 | For more Jekyll news see the Static Times news channel (t: [statictimes](https://twitter.com/statictimes)). 23 | 24 | For more Jekyll goodies see the [Awesome Jekyll](https://github.com/planetjekyll/awesome-jekyll) bookmark list or the [Jekyll bookmark category](http://www.thenewdynamic.org/tool/jekyll/) at the (Static is) The New Dynamic site. 25 | 26 | 27 | ## Themes / Templates 28 | 29 | #### Q: Where can I find themes? 30 | 31 | Check the [Dr. Jekyll's Themes](https://drjekyllthemes.github.io/) directory or 32 | 33 | See the [Themes wiki page](https://github.com/jekyll/jekyll/wiki/Themes) at the Jekyll repo site or 34 | 35 | Search Goolge for [jekyll themes](http://google.com/?q=jekyll+themes) 36 | 37 | 38 | #### Q: Can I use Bootstrap with Jekyll? 39 | 40 | Yes, of course. You can use any HTML starter template/boilerplate with Jekyll. 41 | 42 | Jekyll (and GitHub Pages) has built-in support for SCSS, thus, if you use the Bootstrap SCSS version - Jekyll 43 | will auto-build the `bootstrap.css` from the sources letting you change colors, fonts and much more 44 | in `_settings.scss`. 45 | To get started see the `jekyll-bootstrap-theme` (github: [henrythemes/jekyll-bootstrap-theme](https://github.com/henrythemes/jekyll-bootstrap-theme)) - a ready-to-fork starter theme - as a (live) example. 46 | 47 | 48 | #### Q: How can I get started with gem-packaged themes? / Do I need to package my theme into a gem? 49 | 50 | Gem-packaged themes are just an advanced option and in addition they are in development 51 | for (real world) experiments (e.g. think v0.1 as stated by the Ben Balter - the lead designer / manager / dev at GitHub). 52 | 53 | Thus, to conclude do NOT read too much into the official themes docs e.g. as the only or "right" way to design a theme. 54 | Just (continue to) use "classic" themes - there are hundreds to learn from and once you have mastered "classic" themes 55 | you can "graduate" to the master class, that is, using gem-packaged themes. 56 | 57 | Again gem-packaged themes are wonderful and welcome -- remember, however, the party is just getting started: 58 | 59 | - [henrythemes/hello-minima-theme](https://github.com/henrythemes/hello-minima-theme) 60 | 61 | For some "classic" starter themes you may try some of Henry's themes: 62 | 63 | - [henrythemes/hello-jekyll-theme](https://github.com/henrythemes/hello-jekyll-theme) 64 | - [henrythemes/jekyll-starter-theme](https://github.com/henrythemes/jekyll-starter-theme) 65 | - [henrythemes/jekyll-starter-theme-v2](https://github.com/henrythemes/jekyll-starter-theme-v2) 66 | - [henrythemes/jekyll-minimal-theme](https://github.com/henrythemes/jekyll-minimal-theme) 67 | - [henrythemes/jekyll-bootstrap-theme](https://github.com/henrythemes/jekyll-bootstrap-theme) 68 | 69 | For the "state-of-art" what a "classic" theme can do - see the incredible beautiful and 70 | extremely well-documented (incl. a getting started guide and much much more) [Minimal Mikstake (MM) theme](https://github.com/mmistakes/minimal-mistakes) by Michael Rose. Happy Jekylling. 71 | 72 | 73 | #### Q: Where can I find gem-packaged themes? 74 | 75 | See the [Awesome (Gem-Packaged) Jekyll themes page](https://github.com/planetjekyll/awesome-jekyll-themes) 76 | 77 | 78 | ## Getting Help 79 | 80 | 81 | #### Q: Where can I find help? 82 | 83 | Use the official Jekyll talk forum (web: [talk.jekyllrb.org](https://talk.jekyllrb.com/)) 84 | to post your questions and find help on troubleshooting. 85 | 86 | Ask your (Jekyll) friends! 87 | 88 | For GitHub Pages see the [GitHub Pages Troubleshooting Help Pages](https://help.github.com/categories/github-pages-troubleshooting/) 89 | for a start. 90 | 91 | 92 | #### Q: Where can I find Jekyll friends? 93 | 94 | Look for a Jekyll (static site) user group in your city. 95 | 96 | In Europe groups include: 97 | 98 | - @ Vienna, Austria - **Vienna.html** (t: [viennahtml](https://twitter.com/viennahtml)) 99 | 100 | In America groups include: 101 | 102 | - @ New York, New York - **The New Dynamic** (meetup: [The-New-Dynamic](http://meetup.com/The-New-Dynamic/)) 103 | 104 | If there's no Jekyll group yet in your city, why not start one! 105 | If not, try a local Ruby user group (be aware you might run into some Middleman fanatics ;-), 106 | see the [Awesome Events Page @ Planet Ruby](https://github.com/planetruby/awesome-events) for a world-wide listing. 107 | 108 | 109 | ## Troubleshooting 110 | 111 | #### Q: The Markdown page (e.g. `welcome.md`) gets copied 1:1 to the `_site` folder without getting converted to HTML? Why? 112 | 113 | Double check your front matter. Jekyll REQUIRES that your markdown page starts with a front matter section e.g.: 114 | 115 | ``` 116 | --- 117 | layout: page 118 | title: The Front Matters 119 | --- 120 | ``` 121 | 122 | Note: The front matter MUST start and end with three dashes e.g. `---` (not two `--` or four `----` etc.). As a rule: Without front matter there's no preprocessing, that is, conversion from Markdown (`.md`) to Markup (`.html`). 123 | 124 | 125 | #### Q: Why are my page headings (e.g. `##Heading`) not rendered any longer? 126 | 127 | Note: Most markdown converter REQUIRE a space between `##` and `Heading`, thus, change: 128 | 129 | ``` 130 | #Heading One 131 | ##Heading Two 132 | ``` 133 | 134 | to 135 | 136 | ``` 137 | # Heading One 138 | ## Heading Two 139 | ``` 140 | 141 | #### Q: Jekyll doesn't render Markdown when adding HTML tags? 142 | 143 | Note: If you put your markdown inside an HTML block tag (e.g. `div`) - the default setting for Jekyll's markdown converter (e.g. kramdown) 144 | is to pass the text along as is, that is, without any conversion. Example: 145 | 146 | ``` 147 |
148 | A List: 149 | 150 | - Apples 151 | - Oranges 152 | - Blueberries 153 |
154 | ``` 155 | 156 | Use the "magic" markdown attribute to turn on markdown conversion inside an HTML block tag e.g.: 157 | 158 | ``` 159 |
160 | A List: 161 | 162 | - Apples 163 | - Oranges 164 | - Blueberries 165 |
166 | ``` 167 | 168 | ### Posts and Pages 169 | 170 | #### Q: Why are my latest posts not output (when using a `site.posts` loop)? 171 | 172 | Note: By default future posts will not get added to the posts collection. To get future posts added use the 173 | `future: true` setting in `_config.yml`. For example, lets assume today is 2016-10-12. 174 | 175 | ``` 176 | _posts/ 177 | 2016-07-11-new-beerdb-maps.md 178 | 2016-08-12-new-footballdb-build-system.md 179 | 2017-01-25-new-season.md 180 | 181 | ``` 182 | 183 | Than the posts collection above (without `future: true`) will NOT 184 | include the `2017-01-25-new-season.md` post in `site.posts`. 185 | 186 | 187 | #### Q: How can I include markdown blocks in markdown pages? 188 | 189 | You can include markdown blocks from files in your markdown pages with `include` (looks in the `_includes` folder) or 190 | `include_relative` (looks in the current folder of your page). 191 | 192 | Example `article.md`: 193 | 194 | ``` 195 | --- 196 | title: Title 197 | layout: default 198 | --- 199 | 200 | {% include_relative intro.md %} 201 | {% include_relative explanation.md %} 202 | {% include_relative conclusion.md %} 203 | 204 | ``` 205 | 206 | Note: With `include_relative` you can only include files from 207 | the current folder and its subfolders but NOT up the hierachy in parent folders e.g. `..\` 208 | due to the security sandbox. 209 | 210 | 211 | #### Q: How can I include markdown blocks in html pages? 212 | 213 | If your page is a HTML page e.g. `about.html` 214 | you have to capture the included markdown block 215 | and than convert the markdown block with the `markdownify` filter. 216 | 217 | Example `about.html`: 218 | 219 | ``` 220 | {% capture intro %}{% include intro.md %}{% endcapture %} 221 | {{ intro | markdownify }} 222 | ``` 223 | 224 | 225 | ## Syntax Highlighting 226 | 227 | #### Q: How can I get backtick fenced code blocks (e.g. \`\`\`) working (with kramdown)? 228 | 229 | Use the GitHub-Flavored Markdown (GFM) parser / mode. Change your `_config.yml` settings to: 230 | 231 | ``` 232 | markdown: kramdown 233 | 234 | kramdown: 235 | input: GFM 236 | hard_wrap: false 237 | ``` 238 | 239 | For more see the Official [GitHub-Flavored Markdown (GFM) Docu Page](http://kramdown.gettalong.org/parser/gfm.html). 240 | 241 | 242 | ### Q: How can I get backtick fenced code blocks (e.g. \`\`\`) working inside lists (with kramdown)? 243 | 244 | The gist is that the indentation for the code block in lists is determined 245 | by the column number of the first non-space character after the list item marker. Huh? 246 | 247 | Let's use some examples (note the leading spaces get replaced with dots e.g. `·` to help along): 248 | 249 | _Bulleted List_ 250 | 251 | 252 | *·some text => use 2 spaces indentation e.g. 253 | 254 | ``` 255 | $ gem install beerdb 256 | ``` 257 | 258 | *···some text => use 4 spaces indentation e.g. 259 | 260 | ``` 261 | $ gem install beerdb 262 | ``` 263 | 264 | 265 | _Numbered List_ 266 | 267 | 1.·some text => use 3 spaces indentation e.g. 268 | 269 | ``` 270 | $ gem install beerdb 271 | ``` 272 | 273 | **==> If you line up the fenced code block with the "natural" list indentation, it will work.** 274 | 275 | 276 | For more examples, see the [syntax highlighter sandbox list page](http://planetjekyll.github.io/sandbox-syntax-highlighter/lists.html) - [(source)](https://github.com/planetjekyll/sandbox-syntax-highlighter/blob/gh-pages/lists.md). 277 | 278 | 279 | 280 | #### Q: How can I turn on syntax highlighting in code blocks (with kramdown 'n' rouge)? 281 | 282 | Use the `highlighter` and the `kramdown.syntax_highlighter` options. Change your `_config.yml` settings to: 283 | 284 | ``` 285 | highlighter: rouge 286 | 287 | markdown: kramdown 288 | 289 | kramdown: 290 | input: GFM 291 | hard_wrap: false 292 | syntax_highlighter: rouge 293 | ``` 294 | 295 | 296 | #### Q: How can I turn off syntax highlighting in code blocks (with kramdown 'n' rouge)? 297 | 298 | Use the `kramdown.syntax_highlighter_opts.disable` option. Change your `_config.yml` settings to: 299 | 300 | ``` 301 | highlighter: rouge 302 | 303 | markdown: kramdown 304 | 305 | kramdown: 306 | input: GFM 307 | hard_wrap: false 308 | syntax_highlighter: rouge 309 | syntax_highlighter_opts: 310 | disable: true 311 | ``` 312 | 313 | For more see the Official [Rouge Syntax Highlighter Docu Page](http://kramdown.gettalong.org/syntax_highlighter/rouge.html). 314 | 315 | 316 | #### Q: How can I add a CSS syntax highlighter theme for Rouge? 317 | 318 | Note: If you have Rouge configured Jekyll will only highlight / markup your code in 319 | HTML documents using css classes. 320 | 321 | e.g. 322 | 323 | 324 | ```c 325 | printf("Hello, World!"); 326 | ``` 327 | 328 | becomes: 329 | 330 | 331 | ``` html 332 | 

333 | printf("Hello, World!");
334 |
335 | 336 | ``` 337 | 338 | As step two you have to add css styles to your site's css folder. You can use the 339 | rouge command line tool called `rougify` to get a copy of your theme. 340 | For example, to save the css styles for the monokai.sublime theme 341 | to the file `syntax.css` try: 342 | 343 | 344 | ``` 345 | $ rougify style monokai.sublime > syntax.css 346 | ``` 347 | 348 | Finally as step three make sure you include / load the css styles for the syntax highlighter in your HTML template e.g. 349 | 350 | ``` html 351 | 352 | ``` 353 | That's it. 354 | 355 | Tip: Looking for more themes? Rouge aims to be a drop-in replacement for pygments (e.g. uses the same css style classes), 356 | thus, you can (re)use all pygments css themes. 357 | 358 | 359 | #### Q: What languages (lexers) are supported by Rouge? 360 | 361 | Use: 362 | 363 | ``` 364 | $ rougify list 365 | ``` 366 | 367 | to see an up-to-date list. For version 1.3.1 the languages include: 368 | 369 | apache • 370 | applescript • 371 | c • 372 | clojure (clj,cljs) • 373 | coffeescript (coffee,coffee-script) • 374 | common_lisp (cl,common-lisp,elisp,emacs-lisp) • 375 | conf (config,configuration) • 376 | cpp (c++) • 377 | csharp (c#,cs) • 378 | css • 379 | CowScript • 380 | dart • 381 | diff (patch,udiff) • 382 | elixir (elixir,exs) • 383 | erb (eruby,rhtml) • 384 | erlang (erl) • 385 | factor • 386 | gherkin (cucumber,behat) • 387 | glsl • 388 | go (golang) • 389 | groovy • 390 | haml (HAML) • 391 | handlebars (hbs,mustache) • 392 | haskell (hs) • 393 | html • 394 | http • 395 | ini • 396 | io • 397 | java • 398 | javascript (js) • 399 | json • 400 | json-doc • 401 | liquid • 402 | literate_coffeescript (litcoffee) • 403 | literate_haskell (lithaskell,lhaskell,lhs) • 404 | llvm • 405 | lua • 406 | make (makefile,mf,gnumake,bsdmake) • 407 | markdown (md,mkd) • 408 | matlab (m) • 409 | moonscript (moon) • 410 | nginx • 411 | nim (nimrod) • 412 | objective_c (objc) • 413 | ocaml • 414 | perl (pl) • 415 | php (php3,php4,php5) • 416 | plaintext (text) • 417 | powershell (posh) • 418 | praat • 419 | prolog • 420 | properties • 421 | puppet (pp) • 422 | python (py) • 423 | qml • 424 | r (R,s,S) • 425 | racket • 426 | ruby (rb) • 427 | rust (rs) • 428 | sass • 429 | scala • 430 | scheme • 431 | scss • 432 | sed • 433 | shell (bash,zsh,ksh,sh) • 434 | slim • 435 | smalltalk (st,squeak) • 436 | sml (ml) • 437 | sql • 438 | swift • 439 | tcl • 440 | tex • 441 | toml • 442 | tulip (tlp) • 443 | vb (visualbasic) • 444 | viml (vim,vimscript,ex) • 445 | xml • 446 | yaml (yml) 447 | 448 | 449 | 450 | ## GitHub Pages 451 | 452 | #### Q: What Jekyll plugins can I use on GitHub Pages? 453 | 454 | See the [GitHub Pages Dependency Versions](https://pages.github.com/versions/) page 455 | listing all installed (white-listed) Jekyll Plugins. 456 | In Nov/2016 the list includes: 457 | 458 | - **Coffeescript** (github: [jekyll/jekyll-coffeescript](https://github.com/jekyll/jekyll-coffeescript)) - a CoffeeScript converter 459 | - **Sass Converter** (github: [jekyll/jekyll-sass-converter](https://github.com/jekyll/jekyll-sass-converter)) - a basic Sass converter 460 | - **Mentions** (github: [jekyll/jekyll-mentions](https://github.com/jekyll/jekyll-mentions)) - @mention support for your site 461 | - **Redirect From** (github: [jekyll/jekyll-redirect-from](https://github.com/jekyll/jekyll-redirect-from)) - seamlessly specify multiple redirection URLs for your pages and posts 462 | - **Sitemap** (github: [jekyll/jekyll-sitemap](https://github.com/jekyll/jekyll-sitemap)) - automatically generate a sitemap.xml for your site 463 | - **Feed** (github: [jekyll/jekyll-feed](https://github.com/jekyll/jekyll-feed)) - generate an Atom feed of your posts 464 | - **Avatar** (github: [benbalter/jekyll-avatar](https://github.com/benbalter/jekyll-avatar)) - rendering GitHub avatars 465 | - **Gist** (github: [jekyll/jekyll-gist](https://github.com/jekyll/jekyll-gist)) - liquid tag for displaying GitHub Gists 466 | - **Github Metadata** (github: [jekyll/github-metadata](https://github.com/jekyll/github-metadata)) - access site.github metadata 467 | - **Paginate** (github: [jekyll/jekyll-paginate](https://github.com/jekyll/jekyll-paginate)) - default pagination generator 468 | - **SEO Tag** (github: [](https://github.com/jekyll/jekyll-seo-tag)) - adds metadata tags for search engines and social networks to better index and display your site's content 469 | - **Emoji** (github: [jekyll/jemoji](https://github.com/jekyll/jemoji)) - adds GitHub-flavored emojis 470 | 471 | 472 | ## Liquid Templates 473 | 474 | #### Q: How can I post (escape) code snippets that include curly brackets `{{ }}`? 475 | 476 | Wrap your code snippets with `{% raw %}`..`{% endraw %}` tags. Example: 477 | 478 | Before: 479 | 480 | ```liquid 481 | {% assign words = content | number_of_words %} 482 | {% if words < 360 %} 483 | 1 min 484 | {% else %} 485 | {{ words | divided_by:180 }} mins 486 | {% endif %} 487 | ``` 488 | 489 | After: 490 | 491 | ```liquid 492 | {% raw %} 493 | {% assign words = content | number_of_words %} 494 | {% if words < 360 %} 495 | 1 min 496 | {% else %} 497 | {{ words | divided_by:180 }} mins 498 | {% endif %} 499 | {% endraw %} 500 | ``` 501 | 502 | Note: Unless escaped (with raw) `{{ }}` and `{% %}` get processed by Jekyll 503 | as Liquid template tags/directives/macros. 504 | 505 | 506 | 507 | ## History / Trivia 508 | 509 | #### Q: Why is the Jekyll static site generator called Jekyll (and not Hyde or [your name here])? 510 | 511 | Tom Preston-Werner started to put together some Ruby scripts that let you 512 | "[Blog Like a Hacker](http://tom.preston-werner.com/2008/11/17/blogging-like-a-hacker.html)" back in 2008 513 | and published the package as Jekyll with 514 | the tagline "Transform your text into a monster" and a black and white theme. 515 | 516 | The name is inspired by "[The Strange Case of Dr. Jekyll and Mr. Hyde](http://drjekyllthemes.github.io/jekyll-book-theme/)" - a novella written by 517 | Scottish author Robert Louis Stevenson first published in 1886 in London. 518 | Why? Read the novella online - generated using the Jekyll world classics book theme ;-) 519 | Spoiler alert: Dr. Jekyll and Mr. Hyde is one and only one person. 520 | 521 | 522 | 523 | 524 | ## Meta 525 | 526 | **License** 527 | 528 | The Jekyll FAQs is dedicated to the public domain. 529 | Use it as you please with no restrictions whatsoever. 530 | 531 | **Questions? Comments?** 532 | 533 | Post them to the [wwwmake forum](http://groups.google.com/group/wwwmake). Thanks! 534 | 535 | -------------------------------------------------------------------------------- /GITHUB.md: -------------------------------------------------------------------------------- 1 | Quickref Series @ Planet Jekyll 2 | 3 | [Jekyll](https://github.com/planetjekyll/quickrefs/blob/master/JEKYLL.md) • 4 | [Octopress](https://github.com/planetjekyll/quickrefs/blob/master/OCTOPRESS.md) • 5 | [GitHub Pages](https://github.com/planetjekyll/quickrefs/blob/master/GITHUB.md) • 6 | [YAML (for Datafiles)](https://github.com/planetjekyll/quickrefs/blob/master/YAML.md) • 7 | [WordPress](https://github.com/planetjekyll/quickrefs/blob/master/WORDPRESS.md) 8 | 9 | 10 | # GitHub Pages Quick Reference (Cheat Sheet) 11 | 12 | ## Table of Contents 13 | 14 | - GitHub Pages (`site.github`, sitemap, ...) 15 | 16 | 17 | ## GitHub Pages 18 | 19 | - [`pages.github.com`](https://pages.github.com/) 20 | 21 | What Jekyll version and plugins get used? 22 | 23 | - [`pages.github.com/versions`](https://pages.github.com/versions), for example (update Jan/2015): 24 | 25 | Library | Version 26 | --------------------- | ----------- 27 | jekyll | 2.4.0 28 | jekyll-coffeescript | 1.0.1 29 | jekyll-sass-converter | 1.2.0 30 | kramdown | 1.5.0 31 | liquid | 2.6.1 32 | pygments.rb | 0.6.0 33 | jemoji | 0.4.0 34 | jekyll-mentions | 0.2.1 35 | jekyll-redirect-from | 0.6.2 36 | jekyll-sitemap | 0.6.3 37 | github-pages | 32 38 | ruby | 2.1.1 39 | 40 | 41 | ### `site.github` Variables 42 | 43 | ``` 44 | site.github.contributors -- A list of your project's contributors (*) 45 | site.github.public_repositories -- A list of your public repositories (*) 46 | site.github.organization_members -- A list of your organization's public members (*) 47 | ... 48 | ``` 49 | (*) as returned through the contributors/repositories list/organization members API 50 | 51 | Each of these new variables let you use the complete user/repository objects in Jekyll, thus, 52 | you no longer need any client-side JavaScript API calls when showcasing 53 | your projects on GitHub. For more information on displaying metadata 54 | within your Jekyll site, see [Repository metadata on GitHub Pages](https://help.github.com/articles/repository-metadata-on-github-pages/). 55 | 56 | (Source: [`jekyll-github-metadata` gem](https://github.com/jekyll/github-metadata)) 57 | 58 | 59 | ### Sitemap Plugin 60 | 61 | By simply adding the plugin to your site's configuration (`_config.yml`) e.g. 62 | 63 | ``` 64 | gems: 65 | - jekyll-sitemap 66 | ``` 67 | 68 | Jekyll will automatically generate a `sitemaps.org`-compliant sitemap, 69 | making it easier for search engines to index your site's content. 70 | 71 | Note: The sitemap plugin is already added (and white-listed) on GitHub Pages. 72 | 73 | (Source: [`jekyll-sitemap` gem](https://github.com/jekyll/jekyll-sitemap)) 74 | 75 | ### How-To: Use Single `gh-pages` Branch; Delete `master` Branch 76 | 77 | Step 1a) Already has `gh-pages` branch: 78 | 79 | ``` 80 | git checkout gh-pages 81 | git merge master 82 | git push 83 | ``` 84 | 85 | Step 1b) Create `gh-pages` branch: 86 | 87 | ```` 88 | git checkout -b gh-pages 89 | git merge master 90 | git push origin gh-pages 91 | ```` 92 | 93 | Step 2) Make `gh-pages` branch default branch on GitHub via settings tab 94 | 95 | Step 3) Delete `master` branch on GitHub 96 | 97 | ``` 98 | git push origin :master # will delete master branch on remote (that is, github) 99 | 100 | git branch -d master # will delete master branch in local remote 101 | ``` 102 | 103 | Step 4) Delete local git repo and get a fresh clone from GitHub 104 | 105 | ``` 106 | rm -rf 107 | git clone 108 | ``` 109 | 110 | That's it. 111 | 112 | **Bonus: Check if remote is setup with `git remote show `** 113 | 114 | ``` 115 | $ git remote show origin 116 | # => * remote origin 117 | Fetch URL: https://github.com/openbeer/book.git 118 | Push URL: https://github.com/openbeer/book.git 119 | HEAD branch: gh-pages 120 | Remote branch: 121 | gh-pages tracked 122 | Local branch configured for 'git pull': 123 | gh-pages merges with remote gh-pages 124 | Local ref configured for 'git push': 125 | gh-pages pushes to gh-pages (up to date) 126 | ``` 127 | 128 | 129 | 130 | ## Meta 131 | 132 | **License** 133 | 134 | The GitHub Pages Quick Reference (Cheat Sheet) is dedicated to the public domain. 135 | Use it as you please with no restrictions whatsoever. 136 | 137 | **Questions? Comments?** 138 | 139 | Post them to the [wwwmake forum](http://groups.google.com/group/wwwmake). Thanks! 140 | -------------------------------------------------------------------------------- /JEKYLL.md: -------------------------------------------------------------------------------- 1 | Quickref Series @ Planet Jekyll 2 | 3 | [Jekyll](https://github.com/planetjekyll/quickrefs/blob/master/JEKYLL.md) • 4 | [Octopress](https://github.com/planetjekyll/quickrefs/blob/master/OCTOPRESS.md) • 5 | [GitHub Pages](https://github.com/planetjekyll/quickrefs/blob/master/GITHUB.md) • 6 | [YAML (for Datafiles)](https://github.com/planetjekyll/quickrefs/blob/master/YAML.md) • 7 | [WordPress](https://github.com/planetjekyll/quickrefs/blob/master/WORDPRESS.md) 8 | 9 | 10 | # Jekyll Quick Reference (Cheat Sheet) 11 | 12 | ## Table of Contents 13 | 14 | - Jekyll Commands (`build`, `serve`, ...) 15 | - Folder Structure (`_posts` Folder, `_drafts` Folder, ...) 16 | - Global Variables 17 | - Site Variables 18 | - Page Variable 19 | - Liquid Template Filters n Tags 20 | - Permalinks 21 | - Template Examples (`feed.xml`, ...) 22 | 23 | 24 | ## Jekyll Commands 25 | 26 | ``` 27 | $ jekyll help 28 | 29 | jekyll 2.5.3 -- Jekyll is a blog-aware, static site generator in Ruby 30 | 31 | Usage: 32 | 33 | jekyll [options] 34 | 35 | Options: 36 | -s, --source [DIR] Source directory (defaults to ./) 37 | -d, --destination [DIR] Destination directory (defaults to ./_site) 38 | --safe Safe mode (defaults to false) 39 | -p, --plugins PLUGINS_DIR1[,PLUGINS_DIR2[,...]] Plugins directory (defaults to ./_plugins) 40 | --layouts DIR Layouts directory (defaults to ./_layouts) 41 | -h, --help Show this message 42 | -v, --version Print the name and version 43 | -t, --trace Show the full backtrace when an error occurs 44 | 45 | Subcommands: 46 | serve, server, s Serve your site locally 47 | docs Launch local server with docs for Jekyll v2.5.3 48 | build, b Build your site 49 | doctor, hyde Search site and print specific deprecation warnings 50 | new Creates a new Jekyll site scaffold in PATH 51 | help Show the help message, optionally for a given subcommand. 52 | ``` 53 | 54 | ### `build` Command 55 | 56 | ``` 57 | $ jekyll help build 58 | 59 | jekyll build -- Build your site 60 | 61 | Usage: 62 | 63 | jekyll build [options] 64 | 65 | Options: 66 | --config CONFIG_FILE[,CONFIG_FILE2,...] Custom configuration file 67 | --future Publishes posts with a future date 68 | --limit_posts MAX_POSTS Limits the number of posts to parse and publish 69 | --lsi Use LSI for improved related posts 70 | -D, --drafts Render posts in the _drafts folder 71 | --unpublished Render posts that were marked as unpublished 72 | 73 | -q, --quiet Silence output. 74 | -V, --verbose Print verbose output. 75 | ``` 76 | 77 | ### `serve` Command 78 | 79 | ``` 80 | $ jekyll help serve 81 | 82 | jekyll serve [options] 83 | 84 | Options: 85 | -B, --detach Run the server in the background (detach) 86 | -P, --port [PORT] Port to listen on 87 | -H, --host [HOST] Host to bind to 88 | -b, --baseurl [URL] Base URL 89 | 90 | Build Options: 91 | --skip-initial-build Skips the initial site build which occurs before the server is 92 | -w, --[no-]watch Watch for changes and rebuild 93 | --force_polling Force watch to use polling 94 | 95 | plus all build options (see build command) 96 | ``` 97 | 98 | 99 | ## Jekyll Quickstart 100 | 101 | ``` 102 | $ jekyll new my-site 103 | # => New jekyll site installed in ~/my-site 104 | $ cd my-site 105 | $ jekyll build 106 | # => Configuration file: ~/_config.yml 107 | # Source: ~/my-site 108 | # Destination: ~/my-site/_site 109 | # Generating... done. 110 | $ jekyll serve 111 | # => Server address: http://127.0.0.1:4000/ 112 | # Server running... press ctrl-c to stop. 113 | ``` 114 | 115 | Browse your site e.g. open the page @ `http://127.0.0.1:4000` 116 | 117 | 118 | ## Folder Structure 119 | 120 | Minimial: 121 | 122 | ``` 123 | ├── _config.yml # site configuration 124 | ├── _posts # blog posts 125 | | ├── 2015-01-01-week-1-factbook.md # filename format => YEAR-MONTH-DAY-TITLE.MARKUP 126 | | ├── 2015-01-08-week-2-hoe.md 127 | | └── 2015-01-15-week-3-slideshow.md 128 | ├── _layouts 129 | | ├── default.html # master layout template 130 | | └── post.html # blog post template 131 | ├── css 132 | | └── styles.css # styles for pages 133 | ├── feed.xml # web feed template (e.g. in rss or atom format) 134 | └── index.html # index template 135 | ``` 136 | 137 | will result in (with `permalink: date`): 138 | 139 | ``` 140 | └── _site # output build folder; site gets generated here 141 | ├── css 142 | | └── styles.css # styles for pages (copied 1:1 as is) 143 | ├── 2015 144 | | └── 01 145 | | ├── 01 146 | | | └── week-1-factbook.html # blog post page 147 | | ├── 08 148 | | | └── week-2-hoe.html # another blog post page 149 | | └── 15 150 | | └── week-3-slideshow.html # another blog post page 151 | ├── feed.xml # web feed (e.g. in rss or atom format) 152 | └── index.html # index page 153 | ``` 154 | 155 | or result in (with `permalink: /:title.html`): 156 | 157 | ``` 158 | └── _site # output build folder; site gets generated here 159 | ├── css 160 | | └── styles.css # styles for pages (copied 1:1 as is) 161 | ├── week-1-factbook.html # blog post page 162 | ├── week-2-hoe.html # another blog post page 163 | ├── week-3-slideshow.html # another blog post page 164 | ├── feed.xml # web feed (e.g. in rss or atom format) 165 | └── index.html # index page 166 | ``` 167 | 168 | Note: See the `jekyll-minimal-theme` starter kit for an example 169 | [source repo](https://github.com/feedreader/jekyll-minimal-theme) and 170 | [live demo](http://feedreader.github.io/jekyll-minimal-theme). 171 | 172 | 173 | 174 | With post drafts, page collections, data stores and shared building blocks: 175 | 176 | ``` 177 | ├── _config.yml # site configuration 178 | ├── _posts # blog posts 179 | | ├── 2015-01-01-week-1-factbook.md # filename format => YEAR-MONTH-DAY-TITLE.MARKUP 180 | | ├── 2015-01-08-week-2-hoe.md 181 | | └── 2015-01-15-week-3-slideshow.md 182 | ├── _drafts # upcoming posts; not yet published 183 | | ├── week-4-kramdown.md # note: no date required 184 | | └── week-5-feedparser.md 185 | ├── _layouts 186 | | ├── default.html # master layout templates 187 | | ├── book.html # book listing template 188 | | └── post.html # blog post template 189 | ├── _includes # shared building blocks 190 | | ├── footer.html 191 | | └── header.html 192 | ├── _data # data store (formats available .yml, .json, .csv) 193 | | └── members.csv 194 | ├── _books # page collection (for books) 195 | | ├── ruby-under-a-microscope.md 196 | | └── learn-ruby-the-hard-way.md 197 | ├── books 198 | | └── index.html # book listing index template 199 | ├── members.html # member listing template 200 | ├── feed.xml # web feed template (e.g. in rss or atom format) 201 | └── index.html # site index template 202 | ``` 203 | 204 | Note: The `_post`, `_drafts`, `_layouts`, `_includes`, `_data`, `_books`, `_site` folders must start 205 | with an underscore (`_`). 206 | 207 | 208 | ## `_posts` Folder 209 | 210 | The post file name must follow the format: _YEAR-MONTH-DAY-TITLE.MARKUP_ 211 | (e.g. `2015-01-15-week-3-slideshow.md`). 212 | The permalinks can be customized for each post, 213 | but the date and markup language are determined by the file name. 214 | 215 | ``` 216 | ├── _posts 217 | | ├── 2015-01-01-week-1-factbook.md # e.g. date=2015-01-01, markup=md 218 | | ├── 2015-01-08-week-2-hoe.md # date=2015-01-08, markup=md 219 | | └── 2015-01-15-week-3-slideshow.md # date=2015-01-15, markup=md 220 | ``` 221 | 222 | ### Front Matter 223 | 224 | ``` 225 | --- 226 | layout: post 227 | title: "Week #3 - slideshow gem - a free web alternative to PowerPoint and Keynote in Ruby" 228 | --- 229 | ``` 230 | 231 | **Excerpt** 232 | 233 | ``` 234 | --- 235 | excerpt_separator: 236 | --- 237 | 238 | Excerpt 239 | 240 | Out-of-excerpt 241 | ``` 242 | 243 | ### Tips & Tricks 244 | 245 | **Including images and resources** 246 | 247 | ``` 248 | ![Ruby under a Microscope Book Cover]({{site.url}}/i/book-ruby-under-a-microscope.png) 249 | 250 | [Hoe PDF Booklet](http://docs.seattlerb.org/hoe/Hoe.pdf); 6 Pages 251 | ``` 252 | 253 | 254 | ## `_draft` Folder 255 | 256 | Drafts are unpublished posts without a date. 257 | 258 | ``` 259 | ├── _drafts 260 | | ├── week-4-kramdown.md 261 | | └── week-5-feedparser.md 262 | ``` 263 | 264 | ## `_layouts` Folder 265 | 266 | TBD 267 | 268 | ## `_includes` Folder 269 | 270 | TBD 271 | 272 | ## `_data` Folder 273 | 274 | TBD 275 | 276 | ## `_COLLECTION` Folder (e.g `_books`, `_albums`, etc.) 277 | 278 | TBD 279 | 280 | 281 | ## Global Variables 282 | 283 | ``` 284 | site -- Sitewide information plus configuration settings from _config.yml. 285 | page -- Page specific information plus the front matter. 286 | Custom variables set via the front matter will be available here. 287 | content -- In layout files, the rendered content of the Post or Page being wrapped. 288 | Not defined in Post or Page files. 289 | paginator -- When the paginate configuration option is set variable becomes available. 290 | ``` 291 | 292 | 293 | ## Site Variables 294 | 295 | **Built-in** 296 | 297 | ``` 298 | site.time -- The current time (when you run the jekyll command) 299 | site.pages -- A list of all Pages 300 | site.posts -- A reverse chronological list of all Posts 301 | site.related_posts -- If the page processed is a Post, this contains a list of up to ten related Posts. 302 | By default, these are low quality but fast to compute. 303 | For high quality but slow to compute results, run the 304 | jekyll command with the --lsi (latent semantic indexing) option. 305 | site.static_files -- A list of all static files (i.e. files not processed by Jekyll's converter 306 | or Liquid's renderer - getting passed-through/copied over to the_site 307 | folder as-is). Each file has three properties: path, modified_time and extname 308 | site.html_pages -- A list of all HTML Pages. 309 | site.collections -- A list of all the collections. 310 | site.data -- A list containing the data loaded from the files located in the _data folder. 311 | site.documents -- A list of all the documents in every collection. 312 | 313 | site.categories.CATEGORY -- The list of all Posts in category CATEGORY. 314 | site.tags.TAG -- The list of all Posts with tag TAG. 315 | ``` 316 | 317 | **Your Own (Custom)** 318 | 319 | All variables set via the command line and 320 | in your `_config.yml` site configuration are available through the `site` variable. 321 | For example, if you have `url: http://openfootball.github.io` in your configuration file, 322 | then in your Posts and Pages it will be stored in `site.url`. 323 | 324 | If you add in your `_config.yml` site configuration, for example: 325 | 326 | ``` 327 | url: 'http://openfootball.github.io' 328 | title: 'football.db - Open Football Data' 329 | ``` 330 | 331 | than you can use the variables in your posts, pages and templates: 332 | 333 | ``` 334 | site.url -- your site's url 335 | site.title -- your site's title 336 | ``` 337 | 338 | Note: Jekyll does not parse changes to `_config.yml` in watch mode, 339 | you must restart Jekyll to see changes to variables. 340 | 341 | 342 | ## Page Variables 343 | 344 | ``` 345 | page.content -- The content of the Page, rendered or un-rendered depending upon what 346 | Liquid is being processedand what page is. 347 | page.title -- The title of the Page. 348 | page.excerpt -- The un-rendered excerpt of the Page. 349 | page.url -- The URL of the Post without the domain, but with a leading slash, 350 | e.g. /2015/01/15/week-3-slideshow.html 351 | page.date -- The Date assigned to the Post. This can be overridden in a Post's front matter 352 | by specifying a new date/time in the format YYYY-MM-DD HH:MM:SS (assuming UTC), 353 | or YYYY-MM-DD HH:MM:SS +/-TTTT 354 | (to specify a time zone using an offset from UTC. e.g. 2015-01-15 11:11:00 +0900). 355 | page.id -- An identifier unique to the Post (useful in feeds). 356 | e.g. /2015/01/15/week-3-slideshow 357 | page.categories -- The list of categories to which this post belongs. 358 | Categories are derived from the directory structure above the _posts directory. 359 | For example, a post at /ruby/gems/_posts/2015-01-15-week-3-slideshow.md would have 360 | this field set to ['ruby', 'gem']. These can also be specified in the front matter. 361 | page.tags -- The list of tags to which this post belongs. These can be specified in the front matter. 362 | page.path -- The path to the raw post or page. Example usage: Linking back to the page or 363 | post's source on GitHub. This can be overridden in the front matter. 364 | page.next -- The next post relative to the position of the current post in site.posts. 365 | Returns nil for the last entry. 366 | page.previous -- The previous post relative to the position of the current post in site.posts. 367 | Returns nil for the first entry. 368 | ``` 369 | 370 | 371 | 372 | ## Liquid Template Filters n Tags 373 | 374 | ### Standard Filters 375 | 376 | **String Filters** 377 | 378 | ``` 379 | {{ | capitalize }} -- capitalize words in the input sentence 380 | {{ | downcase }} -- convert an input string to lowercase 381 | {{ | upcase }} -- convert an input string to uppercase 382 | {{ | strip_html }} -- strip html from string 383 | {{ | strip_newlines }} -- strip all newlines (\n) from string 384 | {{ | newline_to_br }} -- replace each newline (\n) with html break 385 | {{ 'foofoo' | replace:'foo','bar' }} -- replace each occurrence 386 | # => 'barbar' 387 | {{ 'barbar' | replace_first:'bar','foo' }} -- replace the first occurrence 388 | # => 'foobar' 389 | {{ 'foobarfoobar' | remove:'foo' }} -- remove each occurrence 390 | # => 'barbar' 391 | {{ 'barbar' | remove_first:'bar' }} -- remove the first occurrence 392 | # => 'bar' 393 | {{ 'foobarfoobar' | truncate: 5, '.' }} -- truncate a string down to x characters. 394 | # => 'foob.' It also accepts a second parameter that will append to the string 395 | {{ | truncatewords }} -- truncate a string down to x words 396 | {{ 'bar' | prepend:'foo' }} -- prepend a string 397 | # => 'foobar' 398 | {{ 'foo' | append:'bar' }} -- append a string 399 | # => 'foobar' 400 | {{ "a~b" | split:"~" }} -- split a string on a matching pattern 401 | # => ['a','b'] 402 | {{ "hello" | slice: -3, 3 }} -- slice a string. Takes an offset and length 403 | # => llo 404 | ``` 405 | 406 | **Date Filters** 407 | 408 | ``` 409 | {{ | date }} -- reformat a date 410 | ``` 411 | 412 | **Array Filters** 413 | 414 | ``` 415 | {{ | first }} -- get the first element of the passed in array 416 | {{ | last }} -- get the last element of the passed in array 417 | {{ | join }} -- join elements of the array with certain character between them 418 | {{ | sort }} -- sort elements of the array 419 | {{ | map }} -- map/collect an array on a given property 420 | {{ | size }} -- return the size of an array or string 421 | ``` 422 | 423 | **Numbers, Math Filters** 424 | 425 | ``` 426 | {{ 4 | minus:2 }} #=> 2 -- subtraction 427 | {{ 1 | plus:1 }} #=> 2 -- addition 428 | {{ 5 | times:4 }} #=> 20 -- multiplication 429 | {{ 10 | divided_by:2 }} #=> 5 -- division 430 | {{ 3 | modulo:2 }} #=> 1 -- remainder 431 | 432 | {{ '1' | plus:'1' }} #=>'11' -- note: make sure to use numbers not strings 433 | ``` 434 | 435 | **Escape Filters** 436 | 437 | ``` 438 | {{ | escape }} -- escape a string 439 | {{ | escape_once }} -- returns an escaped version of html without affecting existing escaped entities 440 | ``` 441 | 442 | 443 | ### Jekyll Filters 444 | 445 | **Date, Time Filters** 446 | 447 | ``` 448 | {{ site.time | date_to_rfc822 }} -- Convert date to RFC-822 format 449 | # => Mon, 07 Nov 2008 13:07:54 -0800 (e.g. used in rss feeds) 450 | {{ site.time | date_to_xmlschema }} -- Convert date to XML Schema (ISO 8601) format 451 | # => 2008-11-07T13:07:54-08:00 (e.g. used in atom feeds) 452 | 453 | {{ site.time | date_to_string }} -- Convert date to short format 454 | # => 07 Nov 2008 455 | {{ site.time | date_to_long_string }} -- Convert date to long format 456 | # => 07 November 2008 457 | ``` 458 | 459 | **Where, Group By, Sort Filters** 460 | 461 | ``` 462 | {{ site.members | where:"graduation_year","2014" }} -- Select all the objects in an array where the key 463 | has the given value. 464 | {{ site.members | group_by:"graduation_year" }} -- Group an array's items by a given property e.g. 465 | [{"name"=>"2013", "items"=>[...]}, 466 | {"name"=>"2014", "items"=>[...]}] 467 | {{ page.tags | sort }} -- Sort an array 468 | {{ site.posts | sort: 'author' }} -- Optional args for hashes: 469 | {{ site.pages | sort: 'title', 'last' }} 1. property name 470 | 2. nils order (first or last) 471 | ``` 472 | 473 | **Escape (XML, CGI, URI) Filters** 474 | 475 | ``` 476 | {{ page.content | xml_escape }} -- Escape some text for use in XML 477 | {{ "foo,bar;baz?" | cgi_escape }} -- CGI escape a string for use in a URL; 478 | # => foo%2Cbar%3Bbaz%3F replaces any special characters with appropriate %XX replacements 479 | {{ "foo, bar \baz?" | uri_escape }} -- URI escape a string 480 | # => foo,%20bar%20%5Cbaz? 481 | ``` 482 | 483 | 484 | **Convert (`markdownify`, `slugify`, `sassify`, `jsonify`) Filters** 485 | 486 | ``` 487 | {{ page.excerpt | markdownify }} -- Convert a Markdown-formatted string into HTML 488 | {{ site.data.projects | jsonify }} -- Convert Hash or Array to JSON 489 | {{ some_scss | scssify }} -- Convert a SCSS-formatted string into CSS 490 | {{ some_sass | sassify }} -- Convert a Sass-formatted string into CSS 491 | 492 | {{ "The _config.yml file" | slugify }} -- Convert a string into a lowercase URL "slug"; 493 | # => the-config-yml-file with option 'pretty': spaces and non-alphanumeric chars 494 | {{ "The _config.yml file" | slugify: 'pretty' }} except for ._~!$&'()+,;=@ 495 | # => the-_config.yml-file 496 | ``` 497 | 498 | **Misc Filters** 499 | 500 | ``` 501 | {{ page.content | number_of_words }} -- Count the number of words in some text 502 | # => 1337 503 | {{ page.tags | array_to_sentence_string }} -- Convert an array into a sentence. Useful for listing tags 504 | # => foo, bar, and baz 505 | ``` 506 | 507 | ### Jekyll Tags 508 | 509 | **Include Tag** 510 | 511 | ``` 512 | {% include footer.html %} -- Searches for include file in _includes folder 513 | {% include footer.html param="value" %} You can also pass parameters to an include 514 | 515 | {% include_relative somedir/footer.html %} -- Searches for include file relative to the file where used 516 | ``` 517 | 518 | **Code Syntax Highlighting Tag** 519 | 520 | ``` 521 | {% highlight ruby %} 522 | def main 523 | puts 'Hello World' 524 | end 525 | {% endhighlight %} 526 | ``` 527 | 528 | ``` 529 | {% highlight ruby linenos %} -- Use line numbers 530 | def main 531 | puts 'Hello World' 532 | end 533 | {% endhighlight %} 534 | ``` 535 | 536 | **Gist Tag** 537 | 538 | ``` 539 | {% gist hyde/931c1c8d465a04042403 %} 540 | {% gist hyde/931c1c8d465a04042403 hello_world.rb %} -- You may specify the filename to display 541 | ``` 542 | 543 | (Source: see jekyll-gist gem) 544 | 545 | 546 | 547 | ## Permalinks 548 | 549 | The default `date` permalink is defined as: 550 | 551 | ``` 552 | /:categories/:year/:month/:day/:title.html 553 | ``` 554 | 555 | ### Permalink Variables 556 | 557 | ``` 558 | year -- Year from the Post’s filename 559 | month -- Month from the Post’s filename 560 | i_month -- Month from the Post’s filename without leading zeros. 561 | day -- Day from the Post’s filename 562 | i_day -- Day from the Post’s filename without leading zeros. 563 | short_year -- Year from the Post’s filename without the century. 564 | title -- Title from the Post’s filename 565 | categories -- The specified categories for this Post. 566 | If a post has multiple categories, Jekyll will create a hierarchy 567 | (e.g. /category1/category2). Also Jekyll automatically parses out double slashes in the URLs, 568 | so if no categories are present, it will ignore this. 569 | ``` 570 | 571 | ### Permalink Styles 572 | 573 | **Built-in** 574 | 575 | ``` 576 | date /:categories/:year/:month/:day/:title.html 577 | pretty /:categories/:year/:month/:day/:title/ 578 | none /:categories/:title.html 579 | ``` 580 | 581 | **Examples** 582 | 583 | Given a post named: /2015-01-15-week-3-slideshow.md 584 | 585 | ``` 586 | None specified (date) /2015/01/15/week-3-slideshow.html 587 | pretty /2015/01/15/week-3-slideshow/index.html 588 | /:month-:day-:year/:title.html /01-15-2015/week-3-slideshow.html 589 | /blog/:year/:month/:day/:title /blog/2015/01/15/week-3-slideshow/index.html 590 | ``` 591 | 592 | 593 | ## CSS Preprocessor Example 594 | 595 | 596 | ``` 597 | ├── _config.yml # site configuration (add sass settings) 598 | └── css 599 | ├── _settings.scss # include / partial settings 600 | └── style.scss # main styles 601 | ``` 602 | 603 | will result in: 604 | 605 | ``` 606 | └── _site 607 | └── css 608 | └── style.css # all-in-one styles (converted from scss to css) 609 | ``` 610 | 611 | Example - `_config.yml`: 612 | 613 | ``` 614 | sass: 615 | sass_dir: css # gets used for partial lookup (default is _sass) 616 | ``` 617 | 618 | Example - `_settings.scss`: 619 | 620 | ``` 621 | $font-family: Helvetica, Arial, sans-serif; 622 | 623 | $color-primary: #8b0000; // dark red (ruby) 624 | ... 625 | ``` 626 | 627 | Exampe - `style.scss`: 628 | 629 | ``` 630 | --- 631 | --- 632 | 633 | @import 'settings'; // include partial (will use sass_dir for lookup) 634 | 635 | body { 636 | font-family: $font-family; // use variables, nested rules, and more 637 | } 638 | ... 639 | ``` 640 | Note: Front matter (minimal) 641 | 642 | ``` 643 | --- 644 | --- 645 | ``` 646 | 647 | or with comments 648 | 649 | ``` 650 | --- 651 | # ensure Jekyll converts scss to css 652 | --- 653 | ``` 654 | 655 | required; ensures Jekyll converts `style.scss` to `style.css`; 656 | include all partials (e.g. `_settings.scss`, and so on) with `@import` directives. 657 | 658 | 659 | (Source: [jekyll-sass-converter gem](https://github.com/jekyll/jekyll-sass-converter)) 660 | 661 | 662 | ## Template Examples 663 | 664 | ### Displaying an index of posts 665 | 666 | ```html 667 |
    668 | {% for post in site.posts %} 669 |
  • 670 | {{ post.title }} 671 |
    • 672 | {% endfor %} 673 |
674 | ``` 675 | 676 | ### Displaying an index of posts with excerpts 677 | 678 | ```html 679 |
    680 | {% for post in site.posts %} 681 |
  • 682 | {{ post.title }} 683 | {{ post.excerpt }} 684 |
    • 685 | {% endfor %} 686 |
687 | ``` 688 | 689 | ### Generate web feed e.g. `feed.xml` for last ten posts (in Atom format) 690 | 691 | ```xml 692 | --- 693 | layout: null 694 | --- 695 | 696 | 697 | {{ site.title }} 698 | 699 | 700 | {{ site.time | date_to_xmlschema }} 701 | {{ site.url }}/ 702 | 703 | {{ site.author }} 704 | 705 | Jekyll v{{ jekyll.version }} 706 | 707 | {% for post in site.posts limit: 10 %} 708 | 709 | {{ post.title | xml_escape }} 710 | 711 | {{ post.date | date_to_xmlschema }} 712 | {{ site.url }}{{ post.id }} 713 | {{ post.content | xml_escape }} 714 | 715 | {% endfor %} 716 | 717 | ``` 718 | 719 | Tip: Add feed auto-discovery to your master layout template in the header. Example: 720 | 721 | ```html 722 | 723 | ``` 724 | 725 | Note: You can add more than one feed, for example: 726 | 727 | ```html 728 | 729 | 730 | 731 | ``` 732 | 733 | 734 | 735 | ## Paginator 736 | 737 | ### Paginator Variables 738 | 739 | ``` 740 | paginator.per_page -- Number of Posts per page 741 | paginator.posts -- Posts available for that page 742 | paginator.total_posts -- Total number of Posts 743 | paginator.total_pages -- Total number of Pages 744 | paginator.page -- The number of the current page 745 | paginator.previous_page -- The number of the previous page 746 | paginator.previous_page_path -- The path to the previous page 747 | paginator.next_page -- The number of the next page 748 | paginator.next_page_path -- The path to the next page 749 | ``` 750 | 751 | (Source: see jekyll-paginator gem) 752 | 753 | 754 | ***Render the paginated Posts*** 755 | 756 | ```html 757 | {% for post in paginator.posts %} 758 |

{{ post.title }}

759 |

760 | {{ post.date }} 761 |

762 |
763 | {{ post.content }} 764 |
765 | {% endfor %} 766 | 767 | 780 | ``` 781 | 782 | 783 | ## Meta 784 | 785 | **License** 786 | 787 | The Jekyll Quick Reference (Cheat Sheet) is dedicated to the public domain. 788 | Use it as you please with no restrictions whatsoever. 789 | 790 | **Questions? Comments?** 791 | 792 | Post them to the [wwwmake forum](http://groups.google.com/group/wwwmake). Thanks! 793 | -------------------------------------------------------------------------------- /OCTOPRESS.md: -------------------------------------------------------------------------------- 1 | Quickref Series @ Planet Jekyll 2 | 3 | [Jekyll](https://github.com/planetjekyll/quickrefs/blob/master/JEKYLL.md) • 4 | [Octopress](https://github.com/planetjekyll/quickrefs/blob/master/OCTOPRESS.md) • 5 | [GitHub Pages](https://github.com/planetjekyll/quickrefs/blob/master/GITHUB.md) • 6 | [YAML (for Datafiles)](https://github.com/planetjekyll/quickrefs/blob/master/YAML.md) • 7 | [WordPress](https://github.com/planetjekyll/quickrefs/blob/master/WORDPRESS.md) 8 | 9 | 10 | 11 | # Octopress Quick Reference (Cheat Sheet) 12 | 13 | ## Table of Contents 14 | 15 | - Octopress Commands (`new`, `new page`, `deploy`, ...) 16 | 17 | ## Octopress Commands 18 | 19 | ``` 20 | $ octopress --help 21 | 22 | octopress 3.0.0 -- Octopress is an obsessively designed toolkit for Jekyll blogging. 23 | 24 | Usage: 25 | 26 | octopress [options] 27 | 28 | Options: 29 | -h, --help Show this message 30 | -v, --version Print the name and version 31 | -t, --trace Show the full backtrace when an error occurs 32 | 33 | Subcommands: 34 | new Creates a new site with Jekyll and Octopress scaffolding at the specified path. 35 | docs Launch local server with docs for Octopress v3.0.0.rc.31 and Octopress plugins. 36 | init Add Octopress's default scaffolding to your site. 37 | publish Convert a draft to a normal published post. 38 | unpublish Convert a post to a draft. Command accepts path to post or search string. 39 | isolate Move all posts not matching selected post to _posts/_exile. Command accepts path to post or search string. 40 | integrate Reintegrate posts from _posts/_exile. 41 | deploy Deploy your Octopress site. 42 | ``` 43 | 44 | ## `new` Command 45 | 46 | ``` 47 | $ octopress new --help 48 | 49 | octopress new -- Creates a new site with Jekyll and Octopress scaffolding at the specified path. 50 | 51 | Usage: 52 | 53 | octopress new 54 | 55 | Options: 56 | -f, --force Force creation even if path already exists. 57 | -b, --blank Creates scaffolding but with empty files. 58 | -h, --help Show this message 59 | 60 | Subcommands: 61 | page Add a new page to your Jekyll site. 62 | post Add a new post to your Jekyll site. 63 | draft Add a new draft post to your Jekyll site. 64 | ``` 65 | 66 | ## `new post` Command 67 | 68 | ``` 69 | $ octopress new post --help 70 | 71 | octopress new post -- Add a new post to your Jekyll site. 72 | 73 | Usage: 74 | 75 | octopress new post [options] 76 | 77 | Options: 78 | -d, --date DATE Use 'now' or a String that is parseable by Time#parse. 79 | -tm, --template PATH New post from a template. 80 | -l, --lang LANGUAGE Set a post language (e.g. en, it) for multi-language sites. 81 | -f, --force Overwrite file if it already exists 82 | -s, --slug SLUG Use this slug in filename instead of sluggified post title. 83 | -d, --dir DIR Create post at _posts/DIR/. 84 | -c, --config <CONFIG_FILE>[,CONFIG_FILE2,...] Custom Jekyll configuration file 85 | -h, --help Show this message 86 | ``` 87 | 88 | ## `deploy` Command 89 | 90 | ``` 91 | $ octopress deploy --help 92 | 93 | octopress deploy 1.0.4 -- Deploy your Octopress site. 94 | 95 | Usage: 96 | 97 | octopress deploy [options] 98 | 99 | Options: 100 | --config FILE The path to your config file (default: _deploy.yml) 101 | -h, --help Show this message 102 | 103 | Subcommands: 104 | pull Pull down the published copy of your site into DIR 105 | init Create a configuration file for a deployment method (git, rsync, s3). 106 | add-bucket Add a new S3 bucket and configure it for static websites. Name defaults to bucket_name in config file 107 | ``` 108 | 109 | ## Octopress Quickstart 110 | 111 | ``` 112 | $ octopress new my-site 113 | # => New jekyll site installed in ~/my-site 114 | # Added Octopress scaffold: 115 | # + _templates/ 116 | # + draft 117 | # + page 118 | # + post 119 | $ cd my-site 120 | $ jekyll build 121 | # => Configuration file: ~/_config.yml 122 | # Source: ~/my-site 123 | # Destination: ~/my-site/_site 124 | # Generating... done. 125 | $ jekyll serve 126 | # => Server address: http://127.0.0.1:4000/ 127 | # Server running... press ctrl-c to stop. 128 | ``` 129 | 130 | 131 | ## Meta 132 | 133 | **License** 134 | 135 | The Octopress Quick Reference (Cheat Sheet) is dedicated to the public domain. 136 | Use it as you please with no restrictions whatsoever. 137 | 138 | **Questions? Comments?** 139 | 140 | Post them to the [wwwmake forum](http://groups.google.com/group/wwwmake). Thanks! 141 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | 2 | # Jekyll Quick References (Cheat Sheets) 'n' F.A.Q.s 3 | 4 | **Quickref Series** 5 | 6 | - [Jekyll Quick Reference (Cheat Sheet)](JEKYLL.md) 7 | - [Octopress Quick Reference (Cheat Sheet)](OCTOPRESS.md) 8 | - [GitHub Pages Quick Reference (Cheat Sheet)](GITHUB.md) 9 | - [YAML (for Jekyll Datafiles) Quick Reference (Cheat Sheet)](YAML.md) 10 | - [WordPress <=> Jekyll Theming (Template) Reference (Cheat Sheet)](WORDPRESS.md) 11 | 12 | **F.A.Q.s** 13 | 14 | - [Jekyll FAQs - Frequently Asked Questions (and Answers)](FAQ.md) 15 | -------------------------------------------------------------------------------- /WORDPRESS.md: -------------------------------------------------------------------------------- 1 | Quickref Series @ Planet Jekyll 2 | 3 | [Jekyll](https://github.com/planetjekyll/quickrefs/blob/master/JEKYLL.md) • 4 | [Octopress](https://github.com/planetjekyll/quickrefs/blob/master/OCTOPRESS.md) • 5 | [GitHub Pages](https://github.com/planetjekyll/quickrefs/blob/master/GITHUB.md) • 6 | [YAML (for Datafiles)](https://github.com/planetjekyll/quickrefs/blob/master/YAML.md) • 7 | [WordPress](https://github.com/planetjekyll/quickrefs/blob/master/WORDPRESS.md) 8 | 9 | 10 | # WordPress <=> Jekyll - Template (Theming) Cheat Sheet 11 | 12 | 13 | `bloginfo()` 14 | 15 | ``` 16 | <?php bloginfo('name'); ?> | {{ site.title }} or {{ site.name }} 17 | <?php bloginfo('description'); ?> | {{ site.description }} 18 | <?php bloginfo('url'); ?> | {{ site.url }} 19 | <?php bloginfo('admin_email'); ?> | {{ site.admin.email }} 20 | ``` 21 | 22 | ``` 23 | <?php bloginfo('version'); ?> | {{ jekyll.version }} # predefined 24 | ``` 25 | 26 | 27 | Define in your `_config.yml`: 28 | 29 | ``` 30 | title: Dr Jekyll and Mr Hyde ## or 31 | name: Dr Jekyll and Mr Hyde 32 | description: Just another Jekyll site 33 | url: http://www.example.com 34 | 35 | admin: 36 | email: admin@example.com 37 | ``` 38 | 39 | 40 | `wp_title` 41 | 42 | ``` 43 | <?php wp_title(); ?> | {{ post.title }} or {{ page.title }} 44 | ``` 45 | 46 | 47 | The Loop 48 | 49 | ``` 50 | <?php while( have_posts() ) : the_post(); ?> | {% for post in site.posts %} 51 | <?php the_title(); ?> | {{ post.title }} 52 | <?php the_content(); ?> | {{ post.content }} 53 | ... | ... 54 | <?php endwhile; ?> | {% endfor %} 55 | ``` 56 | 57 | 58 | Includes - `get_header()`, `get_sidebar()`, `get_footer()` 59 | 60 | ``` 61 | <?php get_header(); ?> | {% include header.html %} 62 | <?php get_sidebar(); ?> | {% include sidebar.html %} 63 | <?php get_footer(); ?> | {% include footer.html %} 64 | ``` 65 | -------------------------------------------------------------------------------- /YAML.md: -------------------------------------------------------------------------------- 1 | Quickref Series @ Planet Jekyll 2 | 3 | [Jekyll](https://github.com/planetjekyll/quickrefs/blob/master/JEKYLL.md) • 4 | [Octopress](https://github.com/planetjekyll/quickrefs/blob/master/OCTOPRESS.md) • 5 | [GitHub Pages](https://github.com/planetjekyll/quickrefs/blob/master/GITHUB.md) • 6 | [YAML (for Data Files)](https://github.com/planetjekyll/quickrefs/blob/master/YAML.md) • 7 | [WordPress](https://github.com/planetjekyll/quickrefs/blob/master/WORDPRESS.md) 8 | 9 | 10 | # YAML Quick Reference (Cheat Sheet) for Jekyll Data Files, Front Matter and Collections 11 | 12 | _YAML Ain't Markup Language - a human friendly data serialization standard for all programming languages_ 13 | 14 | 15 | ## Table of Contents 16 | 17 | - Data File Examples 18 | - [List of Key/Value Records e.g. books.yml](#list-of-keyvalue-records) 19 | - [Nested List of Key/Value Records e.g. nav.yml](#nested-list-of-keyvalue-records) 20 | - [Hash (Dictionary) of Key/Value Records e.g. authors.yml](#hash-dictionary-of-keyvalue-records) 21 | - [Multi-File List of Key/Value Records e.g. orgs/jekyll.yml,octopress.yml](#) 22 | - Front Matter Examples 23 | - [List of Key/Value Records e.g. portfolio.html](#) 24 | - [Multi-File List of Key/Value Records w/ Collections e.g. _albums/josquin.html,hayden.html](#) 25 | - More 26 | - [Multi-Line Strings](#multi-line-strings) 27 | - [Inline Style a.k.a. JSON-Style](#) 28 | - [Literal Keys](#literal-keys) 29 | - [More Gotchas](#more-gotchas) 30 | - No Tabs (\t) for Indentation - Use Spaces, Period 31 | - Predefined Boolean and No Value Constants - True/False, Yes/No, On/Off, ~/Null 32 | - [Tools](#tools) 33 | - [References](#references) 34 | 35 | 36 | 37 | ## What's human friendly? 38 | 39 | #### Let's you use comments or blank lines or spaces 40 | 41 | 42 | Example - `themes.yml`: 43 | 44 | ``` yaml 45 | ######################################### 46 | # Dr Jekyll's Themes - Add Your Theme! 47 | 48 | - title: Bootstrap 49 | github: drjekyllthemes/jekyll-bootstrap-theme 50 | branch: gh-pages 51 | author: Edward Hyde 52 | thumbnail: drjekyll-bootstrap.png 53 | license: Public Domain 54 | 55 | # Another (Possible) Formatting Style 56 | 57 | - title : Classics Book # Todo: Rename to World Classics - Why? Why Not? 58 | github : drjekyllthemes/jekyll-book-theme 59 | branch : gh-pages 60 | author : Edward Hyde 61 | thumbnail : drjekyll-book.png 62 | license : Public Domain 63 | ``` 64 | 65 | is the same as: 66 | 67 | ``` yaml 68 | - title: Bootstrap 69 | github: drjekyllthemes/jekyll-bootstrap-theme 70 | branch: gh-pages 71 | author: Edward Hyde 72 | thumbnail: drjekyll-bootstrap.png 73 | license: Public Domain 74 | - title: Classics Book 75 | github: drjekyllthemes/jekyll-book-theme 76 | branch: gh-pages 77 | author: Edward Hyde 78 | thumbnail: drjekyll-book.png 79 | license: Public Domain 80 | ``` 81 | 82 | Note: The colon (`:`) key/value separator MUST (only) be followed by a space, thus, 83 | you can use `title : Classics Books` and so on. 84 | 85 | Note: The number sign / hash (`#`) used for inline end-of-line comments MUST 86 | have both a leading and trailing space e.g. `some text here # comment starts here`, 87 | otherwise the number sign / hash is just part of the string 88 | e.g. `Jekyll - The #1 Static Site Generator` works as expected. 89 | 90 | 91 | 92 | #### Let's you use strings or keys without (requiring) quotes 93 | 94 | ``` yaml 95 | title: Bootstrap 96 | github: drjekyllthemes/jekyll-bootstrap-theme 97 | author: Edward Hyde 98 | ``` 99 | 100 | is the same as: 101 | 102 | ``` yaml 103 | "title": "Bootstrap" 104 | "github": "drjekyllthemes/jekyll-bootstrap-theme" 105 | "author": "Edward Hyde" 106 | ``` 107 | 108 | 109 | **Gotchas** 110 | 111 | When to use quotes for your strings? 112 | 113 | If your string includes a colon (`:`) you MUST quote your string. Otherwise, the colon is interpreted as a key/value separator (e.g. _key: value_). Example: 114 | 115 | ``` yaml 116 | title: "Text Processing with Ruby: Extract Value from the Data That Surrounds You" 117 | title: "Sinatra: Up and Running - Ruby for the Web, Simply" 118 | title: "Using JRuby: Bringing Ruby to Java" 119 | ``` 120 | 121 | Note: You can quote your strings using double quotes (`""`) e.g. "Using JRuby: Bringing Ruby to Java" 122 | or single quotes(`''`) e.g. 'Using JRuby: Bringing Ruby to Java'. 123 | 124 | 125 | 126 | ## Data File Examples 127 | 128 | List of Key/Value Records • 129 | Nested List of Key/Value Records • 130 | Hash (Dictionary) of Key/Value Records • 131 | Multi-File List of Key/Value Records 132 | 133 | 134 | Note: You can browse the examples live in action at the Sandbox Example Site @ Planet Jekyll. 135 | See the [start page](http://planetjekyll.github.io/sandbox) 136 | or the [sandbox site sources](https://github.com/planetjekyll/sandbox). 137 | 138 | 139 | ### List of Key/Value Records 140 | 141 | Book List Example -`books.yml`: 142 | 143 | ``` yaml 144 | - title: "Text Processing with Ruby: Extract Value from the Data That Surrounds You" 145 | author: Rob Miller 146 | cover: 2015/text-processing-with-ruby.jpg 147 | publisher: Pragmatic Bookshelf 148 | date: Nov 2015 149 | pages: 200 pages (est) 150 | book_url: https://pragprog.com/book/rmtpruby/text-processing-with-ruby 151 | 152 | - title: "Learn Ruby the Hard Way" 153 | subtitle: A Simple and Idiomatic Intro to the Imaginative World Of Computational Thinking with Code 154 | edition: 3rd Edition 155 | author: Zed Shaw 156 | cover: 2014/learn-ruby-the-hard-way.jpg 157 | publisher: Addison-Wesley Professional (Zed Shaw's Hard Way Series) 158 | date: Dec 2014 159 | pages: 336 pages 160 | book_url: http://www.informit.com/store/learn-ruby-the-hard-way 161 | 162 | - title: "Sinatra: Up and Running - Ruby for the Web, Simply" 163 | author: Alan Harris, Konstantin Haase 164 | cover: 2011/sinatra-up-and-running.jpg 165 | publisher: O'Reilly Media 166 | date: Dec 2011 167 | pages: 122 pages 168 | book_url: http://shop.oreilly.com/product/0636920019664.do 169 | ``` 170 | 171 | Use like: 172 | 173 | ``` html 174 | {% for book in site.data.books %} 175 | <div> 176 | <a href="{{ book.book_url }}"> 177 | <img src="{{site.url}}/i/{{book.cover}}"> 178 | </a> 179 | {{ book.title }} 180 | {% if book.edition %} 181 | ({{ book.edition}}) 182 | {% endif %} 183 | by {{ book.author }}; 184 | {{ book.publisher }}, {{ book.date }}; {{ book.pages}} 185 | </div> 186 | {% endfor %} 187 | ``` 188 | 189 | 190 | 191 | ### Nested List of Key/Value Records 192 | 193 | Navigation Menu Example -`nav.yml`: 194 | 195 | ``` yaml 196 | - title: Home 197 | href: / 198 | 199 | - title: Learn 200 | href: /learning-resources/ 201 | subcategories: 202 | - title: Learning topic one 203 | href: /learn1/ 204 | - title: Learning topic two 205 | href: /learn2/ 206 | - title: Learning topic three 207 | href: /learn3/ 208 | 209 | - title: Tools 210 | subcategories: 211 | - title: Tools one 212 | href: /tools1/ 213 | - title: Tools two 214 | href: /tools2/ 215 | 216 | - title: About Us 217 | href: /about-us/ 218 | ``` 219 | 220 | 221 | Use like: 222 | 223 | ``` html 224 | <nav> 225 | <ul> 226 | {% for nav in site.data.nav %} 227 | {% if nav.subcategories %} 228 | <li> 229 | <a href="{{ site.url }}{{ nav.href }}">{{ nav.title }} ▼</a> 230 | <ul> 231 | {% for subcategory in nav.subcategories %} 232 | <li><a href="{{ site.url }}{{ subcategory.href }}">{{ subcategory.title }}</a></li> 233 | {% endfor %} 234 | </ul> 235 | </li> 236 | {% else %} 237 | <li> 238 | <a href="{{ site.url }}{{ nav.href }}">{{ nav.title }}</a> 239 | </li> 240 | {% endif %} 241 | {% endfor %} 242 | </ul> 243 | </nav> 244 | ``` 245 | 246 | 247 | ### Hash (Dictionary) of Key/Value Records 248 | 249 | Author List Example - `authors.yml`: 250 | 251 | ``` yaml 252 | henry: 253 | name: Dr Henry Jekyll 254 | twitter: henryjekyll 255 | 256 | edward: 257 | name: Edward Hyde 258 | twitter: edhyde 259 | ``` 260 | 261 | 262 | Use like: 263 | 264 | Example 1) Lookup author info in a post 265 | 266 | ``` html 267 | --- 268 | title: A Strange Case 269 | author: henry 270 | --- 271 | 272 | {% assign author = site.data.authors[ page.author ] %} 273 | 274 | <a href="http://twitter.com/{{ author.twitter }}"> 275 | {{ author.name }} 276 | </a> 277 | ``` 278 | 279 | 280 | ### Multi-File List of Key/Value Records 281 | 282 | Note: You can place data files in (sub)folders 283 | of the `_data` folder. 284 | Each folder level will get added to the variable's namespace e.g. `site.data.orgs`. 285 | 286 | 287 | Org Example #1 - `orgs/jekyll.yml`: 288 | 289 | ``` yaml 290 | name: Jekyll 291 | github: jekyll 292 | 293 | members: 294 | - name: Parker Moore 295 | github: parkr 296 | - name: Jordon Bedwell 297 | github: envygeeks 298 | ``` 299 | 300 | Org Example #2 - `orgs/octopress.yml`: 301 | 302 | ``` yaml 303 | name: Octopress 304 | github: octopress 305 | 306 | members: 307 | - name: Brandon Mathis 308 | github: imathis 309 | ``` 310 | 311 | Use like: 312 | 313 | ``` html 314 | <ul> 315 | {% for org_hash in site.data.orgs %} 316 | {% assign org = org_hash[1] %} 317 | <li> 318 | <a href="https://github.com/{{ org.username }}"> 319 | {{ org.name }} 320 | </a> 321 | ({{ org.members | size }} members) 322 | </li> 323 | {% endfor %} 324 | </ul> 325 | ``` 326 | 327 | 328 | 329 | ## Front Matter Examples 330 | 331 | List of Key/Value Records • 332 | Multi-File List of Key/Value Records w/ Collections 333 | 334 | 335 | ### List of Key/Value Records 336 | 337 | Portfolio Example, Part 1/2 (Front Matter) - `portfolio.html`: 338 | 339 | ``` yaml 340 | --- 341 | layout: default 342 | title: Histories, Tragedies and Comedies 343 | portfolio: 344 | - title: Richard II 345 | category: History 346 | cover: richard-ii.jpg 347 | - title: Henry VI, Part 1 348 | category: History 349 | cover: henry-vi-1.png 350 | - title: Romeo and Juliet 351 | category: Tragedy 352 | cover: romeo-n-juliet.jpg 353 | - title: Hamlet 354 | category: Tragedy 355 | cover: hamlet.gif 356 | - title: Antony and Cleopatra 357 | category: Tragedy 358 | cover: antony-n-cleopatra.jpg 359 | - title: All's Well That Ends Well 360 | author: Comedy 361 | cover: alls-well-that-ends-well.jpg 362 | - title: A Midsummer Night's Dream 363 | author: Comedy 364 | cover: a-midsummer-nights-dream.jpg 365 | --- 366 | ``` 367 | 368 | Use like: 369 | 370 | Portfolio Example, Part 2/2 (Continued) - `portfolio.html`: 371 | 372 | ``` html 373 | <h1>{{ page.title }} 374 | 375 | <div class='porfolio'> 376 | {% for work in page.portfolio %} 377 | 378 | <div class='work'> 379 | <img src="{{site.url}}/i/portfolio/{{work.cover}}"> 380 | {{ work.title }} // {{ work.category }} 381 | </div> 382 | 383 | {% endfor %} 384 | </div> 385 | ``` 386 | 387 | Note: The portfolio is defined inside the page (in the front matter), thus, 388 | use `page.portfolio` instead of ~~`site.data.portfolio`~~ to reference (e.g. loop over) the list. 389 | 390 | 391 | 392 | ### Multi-File List of Key/Value Records w/ Collections 393 | 394 | 395 | Albums Example #1 - `_albums/josquin.html`: 396 | 397 | ``` yaml 398 | --- 399 | title: "Josquin: Missa De beata virgine and Missa Ave maris stella" 400 | artist: "The Tallis Scholars" 401 | director: "Peter Phillips" 402 | works: 403 | - title: "Missa De beata virgine" 404 | composer: "Josquin des Prez" 405 | tracks: 406 | - title: "Kyrie" 407 | duration: "4:25" 408 | - title: "Gloria" 409 | duration: "9:53" 410 | - title: "Credo" 411 | duration: "9:09" 412 | - title: "Sanctus & Benedictus" 413 | duration: "7:47" 414 | - title: "Agnus Dei I, II & III" 415 | duration: "6:49" 416 | --- 417 | ``` 418 | 419 | Albums Example #2 - `_albums/hayden.html`: 420 | 421 | ``` yaml 422 | --- 423 | title: "Hayden: ??" 424 | artist: "??" 425 | director: "??" 426 | works: 427 | - title: "??" 428 | composer: "??" 429 | tracks: 430 | - title: "??" 431 | duration: "4:25" 432 | - title: "??" 433 | duration: "9:53" 434 | --- 435 | ``` 436 | 437 | Use like: 438 | 439 | Example Catalog - `catalog.html`: 440 | 441 | ``` html 442 | --- 443 | layout: default 444 | title: Album Catalog 445 | --- 446 | {% for album in site.albums %} 447 | <h2>{{ album.title }}</h2> 448 | Performed by {{ album.artist }}{% if album.director %}, directed by {{ album.director }}{% endif %} 449 | {% for work in album.works %} 450 | <h3>{{ work.title }}</h3> 451 | <p>Composed by {{ work.composer }}</p> 452 | <ul> 453 | {% for track in work.tracks %} 454 | <li>{{ track.title }} ({{ track.duration }})</li> 455 | {% endfor %} 456 | </ul> 457 | {% endfor %} 458 | {% endfor %} 459 | ``` 460 | 461 | Note: Using collections you can access **ALL** front matters from all files 462 | from anywhere (not just inside a collection page) using the collection name e.g. `site.albums`. 463 | 464 | 465 | ## More 466 | 467 | 468 | ### Multi-Line Strings 469 | 470 | #### Unfolded (e.g. Keep Newlines) - `|` 471 | 472 | ``` yaml 473 | text: | 474 | There once was a short man from Ealing 475 | Who got on a bus to Darjeeling 476 | It said on the door 477 | "Please don't spit on the floor" 478 | So he carefully spat on the ceiling 479 | ``` 480 | 481 | The leading indent (of the first line) and trailing white space gets stripped e.g. becoming: 482 | 483 | ``` 484 | There once was a short man from Ealing\n 485 | Who got on a bus to Darjeeling\n 486 | It said on the door\n 487 | "Please don't spit on the floor"\n 488 | So he carefully spat on the ceiling\n 489 | ``` 490 | 491 | 492 | 493 | #### Folded (e.g. Strip Newlines) - `>` 494 | 495 | ``` yaml 496 | text: > 497 | Wrapped text 498 | will be folded 499 | into a single 500 | paragraph 501 | 502 | Blank lines denote 503 | paragraph breaks 504 | ``` 505 | 506 | Folded text converts newlines to spaces 507 | and removes leading whitespaces e.g. becoming: 508 | 509 | ``` 510 | Wrapped text will be folded into a single paragraph\n 511 | \n 512 | Blank lines denote paragraph breaks\n 513 | ``` 514 | 515 | ### Inline Style a.k.a. JSON-Style 516 | 517 | Note: As an alternative syntax you can use the inline style for lists (e.g. JSON arrays) 518 | and hashes/dictionaries (e.g. JSON objects). Example: 519 | 520 | ``` yaml 521 | [{ "title": "Bootstrap", 522 | "github": "drjekyllthemes/jekyll-bootstrap-theme", 523 | "author": "Edward Hyde", 524 | "thumbnail": "drjekyll-bootstrap.png" }, 525 | { "title": "Classics Book", 526 | "github": "drjekyllthemes/jekyll-book-theme", 527 | "author": "Edward Hyde", 528 | "thumbnail": "drjekyll-book.png" }] 529 | ``` 530 | 531 | is the same as: 532 | 533 | ``` yaml 534 | [ 535 | { "title": Bootstrap", "github": "drjekyllthemes/jekyll-bootstrap-theme", "author": "Edward Hyde", "thumbnail": "drjekyll-bootstrap.png" }, 536 | { "title": "Classics Book", "github": "drjekyllthemes/jekyll-book-theme", "author": "Edward Hyde", "thumbnail": "drjekyll-book.png" } 537 | ] 538 | ``` 539 | 540 | or the same as: 541 | 542 | ``` yaml 543 | - title : Bootstrap 544 | github : drjekyllthemes/jekyll-bootstrap-theme 545 | author : Edward Hyde 546 | thumbnail : drjekyll-bootstrap.png 547 | - title : Classics Book 548 | github : drjekyllthemes/jekyll-book-theme 549 | author : Edward Hyde 550 | thumbnail : drjekyll-book.png 551 | ``` 552 | 553 | Yes, the JavaScript Object Notation (JSON) is a just another (welcome and working) 554 | formatting style for datafiles. 555 | 556 | 557 | 558 | ### Literal Keys 559 | 560 | Note: You can use upper case letters in your keys (e.g. `Teams`), 561 | add spaces (e.g. `Bundesliga Teams`) and 562 | even start with numbers (e.g. `18 Teams`). Example: 563 | 564 | ``` yaml 565 | 18 Teams: 566 | - Austria Wien 567 | - SC Salzburg 568 | - Sturm Graz 569 | ``` 570 | 571 | 572 | 573 | ## More Gotchas 574 | 575 | **No Tabs (\t) for Indentation - Use Spaces, Period** 576 | 577 | Note: Always use spaces for indentation, period. 578 | Make sure no tabs (`\t`) have somehow ended up in your datafile leading to 579 | unexpected results. 580 | 581 | 582 | 583 | **Predefined Boolean 'n' No Value Constants - True/False, Yes/No, On/Off, ~/Null** 584 | 585 | Note: The boolean `true` and `false` constants e.g.: 586 | 587 | ``` 588 | true, True, TRUE 589 | y, Y, yes, YES, YES 590 | on, ON, ON 591 | false, False, FALSE 592 | n, N, no, No, NO 593 | off, Off, OFF 594 | ``` 595 | 596 | will become boolean values e.g. `true` or `false`. If you want end-up with a string e.g.: 597 | 598 | ``` yaml 599 | recommend: Yes # note: will become => true (boolean) 600 | ``` 601 | 602 | make sure you use a quoted version e.g.: 603 | 604 | ``` yaml 605 | recommend: "Yes" # note: will become => "Yes" (string) 606 | ``` 607 | 608 | 609 | Note: The same holds for the no value null constants e.g.: 610 | 611 | ``` yaml 612 | ~ 613 | null, Null, NULL 614 | ``` 615 | 616 | will become => `null` (no value). Note: A key without a value will end-up with a `null` value (and not an empty string, for example). To get an empty string use `""` e.g.: 617 | 618 | ``` yaml 619 | key1: # note: value will become => null (no value); same as key1: null or key1: ~ 620 | key2: "" # note: value will become => "" (string) 621 | ``` 622 | 623 | 624 | 625 | ## Tools 626 | 627 | - **YAML Online Linter** (web: [yamllint.com](http://www.yamllint.com)) - paste in your YAML and click "Go" - the linter will tell you if your datafile is valid or not, and print out a nice clean formatted version in UTF-8 628 | 629 | 630 | ## References 631 | 632 | **YAML Headquarters** 633 | 634 | - YAML (web: [yaml.org](http://yaml.org)) 635 | - [YAML Reference Card](http://yaml.org/refcard.html) 636 | 637 | **More** 638 | 639 | - [YAML @ Wikipedia](https://en.wikipedia.org/wiki/YAML) 640 | - [YAML Tutorial @ Spacelift](https://spacelift.io/blog/yaml) 641 | 642 | 643 | 644 | ## Meta 645 | 646 | **License** 647 | 648 | The YAML Quick Reference is dedicated to the public domain. 649 | Use it as you please with no restrictions whatsoever. 650 | 651 | **Questions? Comments?** 652 | 653 | Post them to the [wwwmake forum](http://groups.google.com/group/wwwmake). Thanks! 654 | 655 | -------------------------------------------------------------------------------- /notes/JEKYLL.md: -------------------------------------------------------------------------------- 1 | # Jekyll Notes 2 | 3 | 4 | ## `_config.yml` - Configuration 5 | 6 | Example: 7 | 8 | ~~~ 9 | url: 'http://openfootball.github.io' 10 | title: 'football.db - Open Football Data' 11 | 12 | exclude: ['README.md'] 13 | 14 | markdown: 'kramdown' 15 | ~~~ 16 | 17 | Note: Do not use tabs in configuration files (the YAML format forbids tabs; allows only spaces). 18 | 19 | 20 | - site.title e.g. 21 | 22 | 23 | - site.url e.g. 24 | 25 | 26 | - exclude 27 | 28 | Exclude directories and/or files from the conversion. 29 | These exclusions are relative to the site's source directory and cannot be outside the source directory. 30 | 31 | ~~~ 32 | exclude: [DIR, FILE, ...] 33 | ~~~ 34 | 35 | -------------------------------------------------------------------------------- /notes/YAML.md: -------------------------------------------------------------------------------- 1 | # YAML Notes 2 | 3 | 4 | todo: 5 | 6 | add some notes about quotes 7 | e.g. ' in unquotes strings 8 | how to use " - possible? e.g. use 'Jack "Notron" Atom' 9 | 10 | add more notes about boolean 11 | check for values ?? - are boolean or string? 12 | 13 | 14 | 15 | commans work: e.g. 16 | 17 | author: Charles O Nutter, Thomas Enebo, Nick Sieger, Ola Bini, Ian Dees 18 | 19 | todo: Double check. 20 | 21 | If you string includes a comma (`,`) you MUST quote your string. Otherwise, the comma is interpreted as a value list seperator (e.g. _key: value, value, value_). Example: 22 | 23 | ``` yaml 24 | title: "Sinatra: Up and Running - Ruby for the Web, Simply" 25 | title: "" 26 | ``` 27 | 28 | --------------------------------------------------------------------------------