From 029b993225ed63c6e03bf1c965035b9d6a50d741 Mon Sep 17 00:00:00 2001 From: ashmaroli Date: Mon, 10 Apr 2017 02:15:44 +0530 Subject: [PATCH] Fixup tutorial on creating theme from existing HTML templates (#6006) Merge pull request 6006 --- docs/_data/tutorials.yml | 2 +- docs/_sass/_style.scss | 13 ++ ....md => convert-existing-site-to-jekyll.md} | 179 ++++++++++-------- docs/img/jekylllayoutconcept.png | Bin 34133 -> 40209 bytes 4 files changed, 119 insertions(+), 75 deletions(-) rename docs/_tutorials/{create-jekyll-theme.md => convert-existing-site-to-jekyll.md} (57%) diff --git a/docs/_data/tutorials.yml b/docs/_data/tutorials.yml index baf77896..a394345b 100644 --- a/docs/_data/tutorials.yml +++ b/docs/_data/tutorials.yml @@ -4,7 +4,7 @@ - navigation - orderofinterpretation - custom-404-page - - create-jekyll-theme + - convert-site-to-jekyll #- title: Another section # tutorials: diff --git a/docs/_sass/_style.scss b/docs/_sass/_style.scss index c56d6a94..005781b6 100644 --- a/docs/_sass/_style.scss +++ b/docs/_sass/_style.scss @@ -1038,3 +1038,16 @@ code.output { .result { padding: 12px; } + +.image-description { + margin: -20px 0 20px; + padding: 10px 15px; + font-size: 0.81em; + text-align: justify; + background: #5c5c5c; + + pre, code { + font-size: 0.75em; + background: #454545; + } +} diff --git a/docs/_tutorials/create-jekyll-theme.md b/docs/_tutorials/convert-existing-site-to-jekyll.md similarity index 57% rename from docs/_tutorials/create-jekyll-theme.md rename to docs/_tutorials/convert-existing-site-to-jekyll.md index 348ff31a..6a041e8b 100644 --- a/docs/_tutorials/create-jekyll-theme.md +++ b/docs/_tutorials/convert-existing-site-to-jekyll.md @@ -1,38 +1,49 @@ --- layout: tutorials -permalink: /tutorials/create-jekyll-theme/ -title: Create your first Jekyll theme +permalink: /tutorials/convert-site-to-jekyll/ +title: Convert an HTML site to Jekyll --- -If you're looking for themes for your Jekyll site, you don't have to restrict yourself to existing Jekyll themes. It's pretty easy to convert almost any static HTML site into a Jekyll theme. +If you're looking for themes for your Jekyll site, you don't have to restrict yourself to existing Jekyll themes. It's pretty easy to convert almost any static HTML files into a Jekyll website. -In many ways, any site that is currently a static site *already* is a Jekyll site. Jekyll just allows you to automate parts of the site (like inserting pages into templates, rendering lists for navigation, generating feeds and sitemaps, and more) as it processes the files. +In many ways, any site that is currently a static site is *already* a Jekyll website. Jekyll just allows you to automate parts of the site (like inserting pages into templates, rendering lists for navigation, generating feeds and sitemaps, and more) as it processes the files. -Understanding how to convert any HTML site into a Jekyll website will open your world to many more options for Jekyll themes. Instead of searching online for "Jekyll themes," you can choose from the large variety of HTML templates for your site, quickly Jekyll-ize the HTML template as you need to, and build the output with Jekyll. +Understanding how to convert any HTML site into Jekyll templates will open your world to many more options for Jekyll themes. Instead of [searching online for *Jekyll themes*](https://duckduckgo.com/?q=Jekyll+themes), you can choose from the large variety of HTML templates for your site, quickly Jekyll-ize the HTML templates as you need to, and build the output with Jekyll. -Although websites can have sophisticated features and controls, we'll keep things simple in this tutorial. This tutorial contains the following sections: +Although websites can have sophisticated features and controls, we'll keep things simple in this tutorial. -* TOC -{:toc} - -## Understand a basic Jekyll site +## What is a Jekyll Website? First, let's start with a grounding in the basics. Stripping a Jekyll site down to an extremely basic level will help clarify what happens in a Jekyll site. If you haven't already installed the jekyll gem, [install it]({% link _docs/installation.md %}). -A simple Jekyll site might consist of just 3 files: +We'll start with a *basic Jekyll site* consisting of three files: ``` -├── _config.yaml +├── _config.yml ├── _layouts │   └── default.html └── index.md ``` -Manually create these 3 files in a folder called `myjekyllsite`. (Put `default.html` inside a folder called `_layouts`.) Then populate the content of the `default.html` and `index.md` files as follows: +Manually create these three files in a folder called `my_jekyll_site` or whatever suits you the most, and place `default.html` inside a folder named `_layouts`. + +```sh +$ touch _config.yml index.md default.html +$ mkdir _layouts && mv default.html _layouts +``` + +Fire up your favorite editor, and populate the contents of the `default.html` and `index.md` files as follows: + +**_config.yml** + +```yaml +name: My Jekyll Website +``` **_layouts/default.html** ```html + {% raw %}{{ content }}{% endraw %} @@ -48,52 +59,62 @@ title: My page layout: default.html --- -Some **bold** content. +# {% raw %}{{ page.title }}{% endraw %} + +Content is written in [Markdown](https://learnxinyminutes.com/docs/markdown/). Plain text format allows you to focus on your **content**. + + ``` -Now `cd` to `myjekyllsite` and build the site: +Now `cd` to `my_jekyll_site` and serve the site with the built-in server: ``` +cd my_jekyll_site jekyll serve ``` -When you build the site, you get a preview URL such as `http://127.0.0.1:4001/`. The site's files are built in the `_site` folder. +If you have a Gemfile, [use Bundler]({% link _docs/quickstart.md %}#about-bundler) by typing `bundle exec jekyll serve` instead. +{: .note .info} -This is a Jekyll site at the most basic level. Here's what is happening: +When you serve the site, you get a preview URL such as `http://127.0.0.1:4000/` (which is the same as `http://localhost:4000/`). The site's files are built into the `_site` folder by default. -* The `_config.yml` file contains settings that Jekyll uses as it processes your site. An empty config file will use default values for building a Jekyll site. For example, to convert Markdown to HTML, Jekyll will automatically use the [kramdown Markdown filter](https://rubygems.org/gems/kramdown/), without any need to specify it. -* Jekyll looks for files with [front matter tags]({% link _docs/frontmatter.md %}) (the two sets of dashed lines `---` like those in `index.md`) and processes the files (populating site variables, rendering any [Liquid](https://shopify.github.io/liquid/), and converting Markdown to HTML). -* Jekyll pushes the content from all pages and posts into the `{% raw %}{{ content }}{% endraw %}` tags in the layout specified (`default`) in the front matter tags. -* The processed files get written as `.html` files in the `_site` directory. +This is a Jekyll site at the most basic functional level. Here's what is happening: -You can read more about how Jekyll processes the files in [Order of Interpretation](/tutorials/orderofinterpretation/). + * The `_config.yml` file contains settings that Jekyll uses as it processes your site. An empty config file will use default values for building a Jekyll site. For example, to convert [Markdown](https://learnxinyminutes.com/docs/markdown/) to HTML, Jekyll will automatically use the [kramdown Markdown filter](https://rubygems.org/gems/kramdown/), without any need to specify it. + * Jekyll looks for files with [front matter tags]({% link _docs/frontmatter.md %}) (the two sets of dashed lines `---` like those in `index.md`) and processes the files (populating site variables, rendering any [Liquid](https://shopify.github.io/liquid/), and converting Markdown to HTML). + * Jekyll pushes the content from all pages and posts into the `{% raw %}{{ content }}{% endraw %}` variable in the layout specified (`default`) in the front matter tags. + * The processed files get written as `.html` files in the `_site` directory. -With this basic foundation of how a Jekyll site works, you can convert almost any HTML theme into a Jekyll site. The following sections will take you through a step-by-step tutorial on converting an HTML template into a Jekyll site. +You can read more about how Jekyll processes the files in [order of Interpretation]({% link _tutorials/orderofinterpretation.md %}). + +With this basic understanding of how a Jekyll site works, you can convert almost any HTML theme for Jekyll. The following sections will take you through a step-by-step tutorial to do so. ## 1. Create a template for your default layout -Find your HTML theme and save it as a default layout. If you're converting or cloning an existing site, you can right-click the page and view the source code. +Find your HTML theme and save it as a `default` layout. If you're converting or cloning an existing site, you can right-click the page and view the source code. -For example, suppose you're cloning your company site to create a documentation site with the same branding. Or suppose you have a personal site that you built with HTML and now want to make it a Jekyll theme. Get the HTML source code for your site. +For example, suppose you're cloning your company site to create a documentation site with the same branding. Or suppose you have a personal site that you built with HTML and now want to make it a Jekyll site. Get the HTML source code for your site. {: .note .info} -**Note:** Regardless of the site, check the license and make sure you have permission to copy the code. +Regardless of the site, do check the license and make sure you have permission to copy and use the code. -Copy and paste the source code into a file called `default.html`. Put the `default.html` file inside a folder called `_layouts`. This will be the default layout template for your pages and posts — that is, each page or post will use this layout when Jekyll builds the site. +Copy and paste the source code into a file called `default.html`. Put the `default.html` file inside the `_layouts` folder. This will be the default layout template for your pages and posts — that is, each page or post will use this layout when Jekyll builds the site. -Note that in looking for templates, you want the HTML output of the template. If the template has PHP tags or other dynamic scripts, these dynamic elements will need to be converted to HTML or to [Liquid](https://shopify.github.io/liquid/) scripting where possible. Jekyll uses Liquid in its templating system to retrieve dynamic content. +Note that in looking for templates, you want the HTML output of the template. If the template has PHP tags or other dynamic scripts, these dynamic elements will need to be converted to HTML or to [Liquid](https://shopify.github.io/liquid/). Liquid is [Jekyll templating system]({% link _docs/templates.md %}) to retrieve dynamic content. -Open `default.html` into your browser locally to ensure the site looks and functions like it does online. You will likely need to adjust CSS, JS, and image paths so they work. +Open `default.html` into your browser locally to ensure the site looks and behaves like it does online. You will likely need to adjust CSS, JS, and image paths so they work. For example, if the paths were relative on the site you copied, you'll need to either download the same assets into your Jekyll site or use absolute paths to the same assets in the cloud. (Syntax such as `src="//` requires a prefix such as `src="http://` to work in your local browser.) -Jekyll provides some [filters](/docs/templates/#filters) to prepend a site URL before path. For example, you could preface your stylesheet like this: +Jekyll provides some [filters]({% link _docs/templates.md %}#filters) to prepend a site URL before path. For example, you could preface your stylesheet like this: ```liquid {% raw %}{{ "/assets/style.css" | relative_url }}{% endraw %} ``` -The `relative_url` filter will prepend the `baseurl` value from your config file to the input. This is useful if your site is hosted at a subpath rather than the root of the domain (for example, `http://mysite.com/blog/`). +The `relative_url` filter will prepend the [`baseurl`](https://byparker.com/blog/2014/clearing-up-confusion-around-baseurl/) value from your config file (as`blog` for instance) to the input. This is useful if your site is hosted at a subpath rather than at the root of the domain (for example, `http://mysite.com/blog/`). You can also use an `absolute_url` filter. This filter will prepend the `url` *and* `baseurl` value to the input: @@ -101,7 +122,7 @@ You can also use an `absolute_url` filter. This filter will prepend the `url` *a {% raw %}{{ "/assets/style.css" | absolute_url }}{% endraw %} ``` -Again, both `url` and `baseurl` must be defined in your site's config file, like this: +Again, both `url` and `baseurl` can be defined in your site's config file, like this: ``` url: http://mysite.com @@ -114,7 +135,7 @@ Note that the `url` property of any page begins with a forward slash (`/`), so o You don't have to prepend filters to link paths like this. You could also use relative links across your entire site. However you decide to code the paths to your assets, make sure they render correctly. -Does your local `default.html` page look good in your browser? Are all images, styles, and other elements showing up correctly? If so, great. Keep going. You'll use this template as the layout for all your pages and posts. +Does your local `default.html` page look good in your browser? Are all images, styles, and other elements showing up correctly? If so, great. Keep going. You can use this template as the layout for all your pages and posts or create as many templates as you need. In the next section, you'll blank out the content of the layout and replace it with placeholder tags that get populated dynamically with your Jekyll pages. @@ -122,7 +143,7 @@ In the next section, you'll blank out the content of the layout and replace it w In `default.html`, find where the page content begins (usually at `h1` or `h2` tags). Replace the title that appears inside these tags with `{% raw %}{{ page.title }}{% endraw %}`. -Remove the page content (but not code from the top nav, sidebar, or footer) and replace the page content with `{% raw %}{{ content }}{% endraw %}`. +Remove the content part (keep everything else: navigation menu, sidebar, footer, etc.) and replace it with `{% raw %}{{ content }}{% endraw %}`. Check the layout again in your browser and make sure you didn't corrupt or alter it up by inadvertently removing a crucial `div` tag or other element. The only change should be to the title and page content, which are now blanked out or showing the placeholder tag. @@ -144,17 +165,17 @@ Some page content here... Create another page for testing called `about.md` with similar front matter tags. {: .note .info} -**Note:** If you don't specify a layout in your pages, Jekyll will automatically use the template labeled `default`. We specify it here only to make it explicit what's happening. +If you don't specify a layout in your pages, Jekyll will simply render that page as an unstyled basic HTML page. ## 4. Add a configuration file -Add a `_config.yml` file in your root directory. In `_config.yml`, you can optionally specify the markdown filter you want. By default, [kramdown](https://kramdown.gettalong.org/)) is used (without the need to specify it). If no other filter is specified, your config file will automatically apply the following as a default setting: +Add a `_config.yml` file in your root directory. In `_config.yml`, you can optionally specify the markdown filter you want. By default, [kramdown](https://kramdown.gettalong.org/) is used (without the need to specify it). If no other filter is specified, your config file will automatically apply the following as a default setting: ``` markdown: kramdown ``` -You can also specify [some options](https://kramdown.gettalong.org/converter/html.html) for kramdown to make it behave more like Github-flavored Markdown: +You can also specify [some options](https://kramdown.gettalong.org/converter/html.html) for kramdown to make it behave more like [GitHub Flavored Markdown (GFM)](https://github.github.com/gfm/): ``` kramdown: @@ -181,7 +202,7 @@ layout: homepage This page would then use the `homepage.html` template in the `_layouts` folder. -You can even set [default front matter tags](/docs/configuration/#front-matter-defaults) for pages, posts, or [collections]({% link _docs/collections.md %}) in your `_config.yml` file so that you don't have to specify the layout in your front matter tags. However, setting defaults is more advanced than this basic tutorial will cover. +You can even set [default front matter tags]({% link _docs/configuration.md %}#front-matter-defaults) for pages, posts, or [collections]({% link _docs/collections.md %}) in your `_config.yml` file so that you don't have to specify the layout in the front matter variables. Anywayd, setting defaults is beyond the scope of this tutorial, let's get back to work. ## 6. Configure site variables @@ -207,22 +228,22 @@ title: ACME Website Any properties you add in your `_config.yml` file are accessible through the `site` namespace. Similarly, any properties in your page's front matter are accessible through the `page` namespace. Use dot notation after `site` or `page` to access the value. -Stop your Jekyll server (**Ctrl + C**) and restart it. Verify that the `title` tags are populating correctly. +Stop your Jekyll server with Ctrl + C and restart it. Verify that the `title` tags are populating correctly. {: .note .info} -**Note:** Every time you modify your config file, you have to restart Jekyll for the changes to take effect. When you modify other files, Jekyll automatically picks up the changes when it rebuilds. +Every time you modify your config file, you have to restart Jekyll for the changes to take effect. When you modify other files, Jekyll automatically picks up the changes when it rebuilds. -If you have other variables to populate in your site, do so following this same pattern. +If you have other variables to populate in your site, rinse and repeat. ## 7. Show posts on a page -It's common to show a list of posts on the homepage. First, let's create some posts so that our loop will have something to display. +It's common to show a list of posts on the homepage. First, let's create some posts so that we have something to showcase. Add some posts in a `_posts` folder following the standard `YYYY-MM-DD-title.md` post format: -* `2017-01-02-my-first-post.md` -* `2017-01-15-my-second-post.md` -* `2017-02-08-my-third-post.md` + * `2017-01-02-my-first-post.md` + * `2017-01-15-my-second-post.md` + * `2017-02-08-my-third-post.md` In each post, add some basic content: @@ -235,14 +256,15 @@ layout: default Some sample content... ``` -Now let's create a layout that will display the posts. Create a new file in `_layouts` called `home.html`. In your `home.html` layout, add the following logic: +Now let's create a layout that will display the posts. Create a new file in `_layouts` called `home.html` and add the following logic: ``` --- layout: default --- -{% raw %}