New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

New tutorial: Convert an HTML site to Jekyll #5881

Merged
merged 8 commits into from Apr 4, 2017

Conversation

Projects
None yet
7 participants
@tomjoht
Contributor

tomjoht commented Feb 11, 2017

This tutorial explains how to convert an HTML site to Jekyll. We need this tutorial for several reasons. First, theming is one of Jekyll's strengths and should be explained more clearly in the docs. Second, there aren't that many Jekyll themes, but there are thousands of HTML web templates available. Finally, many tech writers that use Jekyll need to clone their company sites to provide seamless branding of their documentation content. They need this tutorial.

I know there are some existing tutorials online for creating Jekyll sites, but here I've tried to simplify the process and make it easier. This tutorial will be added to the Tutorials navigation.

This tutorial should be listed in the Tutorials nav. I'm waiting on PR 5698 to go live before I can start adding links to that navigation.

New tutorial: Convert an HTML site to Jekyll
This tutorial explains how to convert an HTML site to Jekyll. We need this tutorial for several reasons. First, theming is one of Jekyll's strengths and should be explained more clearly in the docs. Second, there aren't that many Jekyll themes, but there are thousands of HTML web templates available. Finally, many tech writers that use Jekyll need to clone their company sites to provide seamless branding of their documentation content. They need this tutorial.

I know there are some existing tutorials online for creating Jekyll sites, but here I've tried to simplify the process and make it easier. This tutorial will be added to the Tutorials navigation.

This tutorial should be listed in the Tutorials nav. I'm waiting on [PR 5698](#5698) to go live before I can start adding links to that navigation.
@ashmaroli

This comment has been minimized.

Show comment
Hide comment
@ashmaroli

ashmaroli Feb 11, 2017

Member

I like it. 👍

Now, if only there was a plugin to automate this..........

Member

ashmaroli commented Feb 11, 2017

I like it. 👍

Now, if only there was a plugin to automate this..........

@DirtyF

This comment has been minimized.

Show comment
Hide comment
@DirtyF

DirtyF Feb 11, 2017

Member

That's how I started using Jekyll in the first place, by iteration :

  • add a _config.yml file in my existing static site
  • split {{content}} and layouts
  • split layouts in includes files when necessary (head, header, footer, etc.)
  • use variables in layouts and includes (_config.yml, _data or YFM)
  • add basic plugins like jekyll-feed, jekyll-sitemap, jekylll-seo-tag, etc.
  • etc.

I liked how you can simply start from HTML and progressively turn your static site into a Jekyll website (and not the other way around).

Member

DirtyF commented Feb 11, 2017

That's how I started using Jekyll in the first place, by iteration :

  • add a _config.yml file in my existing static site
  • split {{content}} and layouts
  • split layouts in includes files when necessary (head, header, footer, etc.)
  • use variables in layouts and includes (_config.yml, _data or YFM)
  • add basic plugins like jekyll-feed, jekyll-sitemap, jekylll-seo-tag, etc.
  • etc.

I liked how you can simply start from HTML and progressively turn your static site into a Jekyll website (and not the other way around).

@tomjoht

This comment has been minimized.

Show comment
Hide comment
@tomjoht

tomjoht Mar 13, 2017

Contributor

This PR hasn't really progressed. Is there anything blocking it from being merged?

Contributor

tomjoht commented Mar 13, 2017

This PR hasn't really progressed. Is there anything blocking it from being merged?

Show outdated Hide outdated _tutorials/convert-html-site-to-jekyll.md
## 2. Establish the Default Layout
Find your HTML theme and save it as a default layout. If you're converting or cloning (with permission to do so) an existing site, you can right-click the page and view the source code. Copy and paste the source code into a file called `default.html` inside a folder called `_layouts`. This will be the layout template for your pages and posts.

This comment has been minimized.

@pathawks

pathawks Mar 13, 2017

Member

(with permission to do so)

This sounds scary. What are you trying to communicate?

@pathawks

pathawks Mar 13, 2017

Member

(with permission to do so)

This sounds scary. What are you trying to communicate?

This comment has been minimized.

@tomjoht

tomjoht Mar 13, 2017

Contributor

I'm addressing a scenario where you have an existing static site (like your company site) and you want to convert it into a Jekyll site. For example, I recently did this with a podcast site. The original site looked like this: writethedocs.org. It's a sphinx-generated site. I cloned it to Jekyll to create a podcast-feature on the site: podcast.writethedocs.org. The podcast page (Jekyll-powered) is an exact clone of the sphinx theme.

There are loads of people looking to do this. When I was in the WordPress world, I had a post on cloning your site into a WP site -- it was the most popular post on my site for a long time.

@tomjoht

tomjoht Mar 13, 2017

Contributor

I'm addressing a scenario where you have an existing static site (like your company site) and you want to convert it into a Jekyll site. For example, I recently did this with a podcast site. The original site looked like this: writethedocs.org. It's a sphinx-generated site. I cloned it to Jekyll to create a podcast-feature on the site: podcast.writethedocs.org. The podcast page (Jekyll-powered) is an exact clone of the sphinx theme.

There are loads of people looking to do this. When I was in the WordPress world, I had a post on cloning your site into a WP site -- it was the most popular post on my site for a long time.

This comment has been minimized.

@pathawks

pathawks Mar 13, 2017

Member

What I mean is: from whom do I need permission?

@pathawks

pathawks Mar 13, 2017

Member

What I mean is: from whom do I need permission?

This comment has been minimized.

@DirtyF

DirtyF Apr 3, 2017

Member

I understand it as an encouragement to check for the LICENSE if any.

@DirtyF

DirtyF Apr 3, 2017

Member

I understand it as an encouragement to check for the LICENSE if any.

Show outdated Hide outdated _tutorials/convert-html-site-to-jekyll.md
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.
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. (Note that syntax such as `src="//` requires a prefix such as `src="http://` to work in your local browser.)

This comment has been minimized.

@pathawks

pathawks Mar 13, 2017

Member

(Note that syntax such as src="// requires a prefix such as src="http:// to work in your local browser.)

What do you mean? If using jekyll serve, the protocol will be http:// already.
I agree that protocol relative URLs are an anti-pattern, but not sure what that has to do with this.

@pathawks

pathawks Mar 13, 2017

Member

(Note that syntax such as src="// requires a prefix such as src="http:// to work in your local browser.)

What do you mean? If using jekyll serve, the protocol will be http:// already.
I agree that protocol relative URLs are an anti-pattern, but not sure what that has to do with this.

This comment has been minimized.

@tomjoht

tomjoht Mar 13, 2017

Contributor

When you copy the source code of a site, it won't render locally because some of the paths to the assets will no longer valid. For example, a path to a CSS reference might look like this in the source code you cloned:

src="//assets/mystyles.css"

This path won't work when you build your Jekyll site. You would have to either populate it with the http URL before assets/mystyles.css, like this: http://somesite.com/assets/mystyles.css. Or you'd have to download mystyles.css and use a relative path to it, like this: /assets/mystyles.css. Or even {{site.baseurl}}/assets/mystyles.css.

@tomjoht

tomjoht Mar 13, 2017

Contributor

When you copy the source code of a site, it won't render locally because some of the paths to the assets will no longer valid. For example, a path to a CSS reference might look like this in the source code you cloned:

src="//assets/mystyles.css"

This path won't work when you build your Jekyll site. You would have to either populate it with the http URL before assets/mystyles.css, like this: http://somesite.com/assets/mystyles.css. Or you'd have to download mystyles.css and use a relative path to it, like this: /assets/mystyles.css. Or even {{site.baseurl}}/assets/mystyles.css.

@pathawks

This comment has been minimized.

Show comment
Hide comment
@pathawks

pathawks Mar 13, 2017

Member

There is good stuff in here, but it seems more focused on a "My First Jekyll Site" than anything to do specifically with refactoring an existing site into a Jekyll site.

Also remember that anything that is currently a static site is already a Jekyll site. There is nothing special that needs to be done for Jekyll to be able to render a site. This is part of the magic of GitHub Pages: a user can just push a static site and everything just works, even if the user has never heard of Jekyll.

Member

pathawks commented Mar 13, 2017

There is good stuff in here, but it seems more focused on a "My First Jekyll Site" than anything to do specifically with refactoring an existing site into a Jekyll site.

Also remember that anything that is currently a static site is already a Jekyll site. There is nothing special that needs to be done for Jekyll to be able to render a site. This is part of the magic of GitHub Pages: a user can just push a static site and everything just works, even if the user has never heard of Jekyll.

@tomjoht

This comment has been minimized.

Show comment
Hide comment
@tomjoht

tomjoht Mar 13, 2017

Contributor

Do you want me to change the title and context? Or should I can close the PR and just publish this tutorial on my own site instead? There's a scarcity of Jekyll themes, and I'm trying to remedy this by helping people understand how easy it is to convert an existing static HTML site into a Jekyll site. Maybe I should include more info up front about how Jekyll can seamlessly plug into any existing site to help automate things?

Contributor

tomjoht commented Mar 13, 2017

Do you want me to change the title and context? Or should I can close the PR and just publish this tutorial on my own site instead? There's a scarcity of Jekyll themes, and I'm trying to remedy this by helping people understand how easy it is to convert an existing static HTML site into a Jekyll site. Maybe I should include more info up front about how Jekyll can seamlessly plug into any existing site to help automate things?

@pathawks

This comment has been minimized.

Show comment
Hide comment
@pathawks

pathawks Mar 14, 2017

Member

@tomjohnson1492 Sorry, I understand you're a bit frustrated that this hasn't gone anywhere.

Perhaps my comments are counter-productive. The last thing that I want to do is discourage you from improving our docs. I am not a member of @jekyll/documentation and I am certainly not a technical writer; I will step aside and let others handle this.

Member

pathawks commented Mar 14, 2017

@tomjohnson1492 Sorry, I understand you're a bit frustrated that this hasn't gone anywhere.

Perhaps my comments are counter-productive. The last thing that I want to do is discourage you from improving our docs. I am not a member of @jekyll/documentation and I am certainly not a technical writer; I will step aside and let others handle this.

@jekyllbot jekyllbot self-assigned this Mar 14, 2017

@tomjoht

This comment has been minimized.

Show comment
Hide comment
@tomjoht

tomjoht Mar 14, 2017

Contributor

@pathawks I really do appreciate your feedback and review. You make some valid points. Cloning someone's website does raise immediate red flags. I can probably address this with a revision and maybe approach it from a "Making your first theme" angle, as you suggested.

Letting a first draft sit for a while is actually good -- it will let me see the content with a fresh perspective, so let me take another crack at it.

Contributor

tomjoht commented Mar 14, 2017

@pathawks I really do appreciate your feedback and review. You make some valid points. Cloning someone's website does raise immediate red flags. I can probably address this with a revision and maybe approach it from a "Making your first theme" angle, as you suggested.

Letting a first draft sit for a while is actually good -- it will let me see the content with a fresh perspective, so let me take another crack at it.

@parkr

This comment has been minimized.

Show comment
Hide comment
@parkr

parkr Mar 31, 2017

Member

@DirtyF @pathawks if this looks good to you, feel free to merge.

Member

parkr commented Mar 31, 2017

@DirtyF @pathawks if this looks good to you, feel free to merge.

@DirtyF

This comment has been minimized.

Show comment
Hide comment
@DirtyF

DirtyF Mar 31, 2017

Member

I kinda hoped @andrewbanchich or @mmistakes would take a quick look at this tutorial before merging 🙏

Member

DirtyF commented Mar 31, 2017

I kinda hoped @andrewbanchich or @mmistakes would take a quick look at this tutorial before merging 🙏

@andrewbanchich

This comment has been minimized.

Show comment
Hide comment
@andrewbanchich

andrewbanchich Mar 31, 2017

@DirtyF As in you'd like us to contribute to it?

@DirtyF As in you'd like us to contribute to it?

@DirtyF

This comment has been minimized.

Show comment
Hide comment
@DirtyF

DirtyF Mar 31, 2017

Member

@andrewbanchich As someone used to adapt existing themes for Jekyll, what's your opinion on this tutorial? Any feedback? Is it a good first overview? What's your workflow?

Member

DirtyF commented Mar 31, 2017

@andrewbanchich As someone used to adapt existing themes for Jekyll, what's your opinion on this tutorial? Any feedback? Is it a good first overview? What's your workflow?

@andrewbanchich

This comment has been minimized.

Show comment
Hide comment
@andrewbanchich

andrewbanchich Mar 31, 2017

@DirtyF Gotcha, I'll check this out this weekend and see what I can contribute!

@DirtyF Gotcha, I'll check this out this weekend and see what I can contribute!

made some updates from previous reviews
I made some updates based on Pat's review. Also, since it's been a couple of weeks since I initially wrote this tutorial, I revised it with fresh eyes and added some more detail and clarity in places.
@tomjoht

This comment has been minimized.

Show comment
Hide comment
@tomjoht

tomjoht Mar 31, 2017

Contributor

I made some updates to the initial draft to add more detail and clarity. I welcome any reviews or other comments that would help make this tutorial stronger. It's really designed for people who are new to Jekyll and want to convert an HTML template into a Jekyll site.

In this tutorial, I try to briefly expose readers to different aspects of theming in a basic way, without diving too deeply into details. There are about 13 different steps, so I'm showing more of an end-to-end process so users can get a sense of the whole (rather than just seeing one single, isolated task).

Contributor

tomjoht commented Mar 31, 2017

I made some updates to the initial draft to add more detail and clarity. I welcome any reviews or other comments that would help make this tutorial stronger. It's really designed for people who are new to Jekyll and want to convert an HTML template into a Jekyll site.

In this tutorial, I try to briefly expose readers to different aspects of theming in a basic way, without diving too deeply into details. There are about 13 different steps, so I'm showing more of an end-to-end process so users can get a sense of the whole (rather than just seeing one single, isolated task).

@andrewbanchich

This comment has been minimized.

Show comment
Hide comment
@andrewbanchich

andrewbanchich Apr 1, 2017

@DirtyF @tomjohnson1492 Nice job! Here's my feedback:

  • I haven't used {% raw %} in the themes I've converted. Maybe to make it simpler you could only use {{ content }} and then explain later the reason why someone may need to use {% raw %}?
  • For nav menus, I think using _data might be overkill for most people. Here is some code I used for a menu:
<!-- Menu -->
<nav id="menu">
	<ul class="links">
        {% for page in site.pages %}
		    {% if page.layout == "home" %}
		        <li><a href="{{ "" | absolute_url }}">{{ page.title }}</a></li>
	    	{% endif %}
		{% endfor %}
		{% for page in site.pages %}
		    {% if page.layout != "home" %}
		        <li><a href="{{ page.url | absolute_url }}">{{ page.title }}</a></li>
		    {% endif %}
		{% endfor %}
	</ul>
	<ul class="actions vertical">
		<li><a href="#" class="button special fit">Get Started</a></li>
		<li><a href="#" class="button fit">Log In</a></li>
	</ul>
</nav>

That way, the "Home" link will always be on top, and the others will automatically appear in the menu when other pages are added.

  • One thing I learned to be careful with in Jekyll is paths. I think there were some updates made to Jekyll that smooth some things out, but I do think it would be important to discuss using filters like relative_url and absolute_url, as well as issues you may come across when setting a site url and base url in _config.ymlwhile serving the site locally and then pushing live.

  • On that note, maybe it would be nice to have a "The Strange and Wonderful World of Jekyll's Idiosyncrasies" section where you discuss common issues that a developer may run into using Jekyll and Liquid tags.

Nice work! I think this is a great idea to get people to start converting more sites.

andrewbanchich commented Apr 1, 2017

@DirtyF @tomjohnson1492 Nice job! Here's my feedback:

  • I haven't used {% raw %} in the themes I've converted. Maybe to make it simpler you could only use {{ content }} and then explain later the reason why someone may need to use {% raw %}?
  • For nav menus, I think using _data might be overkill for most people. Here is some code I used for a menu:
<!-- Menu -->
<nav id="menu">
	<ul class="links">
        {% for page in site.pages %}
		    {% if page.layout == "home" %}
		        <li><a href="{{ "" | absolute_url }}">{{ page.title }}</a></li>
	    	{% endif %}
		{% endfor %}
		{% for page in site.pages %}
		    {% if page.layout != "home" %}
		        <li><a href="{{ page.url | absolute_url }}">{{ page.title }}</a></li>
		    {% endif %}
		{% endfor %}
	</ul>
	<ul class="actions vertical">
		<li><a href="#" class="button special fit">Get Started</a></li>
		<li><a href="#" class="button fit">Log In</a></li>
	</ul>
</nav>

That way, the "Home" link will always be on top, and the others will automatically appear in the menu when other pages are added.

  • One thing I learned to be careful with in Jekyll is paths. I think there were some updates made to Jekyll that smooth some things out, but I do think it would be important to discuss using filters like relative_url and absolute_url, as well as issues you may come across when setting a site url and base url in _config.ymlwhile serving the site locally and then pushing live.

  • On that note, maybe it would be nice to have a "The Strange and Wonderful World of Jekyll's Idiosyncrasies" section where you discuss common issues that a developer may run into using Jekyll and Liquid tags.

Nice work! I think this is a great idea to get people to start converting more sites.

@DirtyF

This comment has been minimized.

Show comment
Hide comment
@DirtyF

DirtyF Apr 1, 2017

Member

👍 for starting with building a simple navigation without data files here, we can link to the dedicated navigation tutorial anyway 😉 .

Member

DirtyF commented Apr 1, 2017

👍 for starting with building a simple navigation without data files here, we can link to the dedicated navigation tutorial anyway 😉 .

@tomjoht

This comment has been minimized.

Show comment
Hide comment
@tomjoht

tomjoht Apr 3, 2017

Contributor

Thanks Andrew. I appreciate your review and suggestions. I'll incorporate these into the tutorial. Re the {% raw %} tags, these won't be visible. They're just used to tell Jekyll to ignore the actual code and to display the tag the raw tags enclose instead. Otherwise Jekyll tries to execute the statement (e.g., an include) and would complain if the reference file is missing.

I like the code sample for the simplified menu. This kind of highlights how different people use Jekyll. For blogs, you only need a few pages. For doc sites, you have hundreds of pages and often no posts.

Contributor

tomjoht commented Apr 3, 2017

Thanks Andrew. I appreciate your review and suggestions. I'll incorporate these into the tutorial. Re the {% raw %} tags, these won't be visible. They're just used to tell Jekyll to ignore the actual code and to display the tag the raw tags enclose instead. Otherwise Jekyll tries to execute the statement (e.g., an include) and would complain if the reference file is missing.

I like the code sample for the simplified menu. This kind of highlights how different people use Jekyll. For blogs, you only need a few pages. For doc sites, you have hundreds of pages and often no posts.

updated based on Andrew's review
I added some updates based on Andrew's review, and also polished up the text in places to improve the readability.
@tomjoht

This comment has been minimized.

Show comment
Hide comment
@tomjoht

tomjoht Apr 3, 2017

Contributor

I incorporated edits from Andrew's review. Mainly, I expanded the page navigation section with a more basic example (rather than just iterating through a data file). In the default layout section, I also included examples with relative_url and absolute_url tags. I cleaned up other sentences for clarity.

Unless anyone has other requests for changes, I'm done with all my edits on this tutorial. I think it's ready to merge.

Contributor

tomjoht commented Apr 3, 2017

I incorporated edits from Andrew's review. Mainly, I expanded the page navigation section with a more basic example (rather than just iterating through a data file). In the default layout section, I also included examples with relative_url and absolute_url tags. I cleaned up other sentences for clarity.

Unless anyone has other requests for changes, I'm done with all my edits on this tutorial. I think it's ready to merge.

Show outdated Hide outdated _tutorials/convert-html-site-to-jekyll.md
{{ "/assets/style.css" | relative_url }}
```
The `relative_url` tag 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/`).

This comment has been minimized.

@ashmaroli

ashmaroli Apr 3, 2017

Member

relative_url and absolute_url are filters not tags

@ashmaroli

ashmaroli Apr 3, 2017

Member

relative_url and absolute_url are filters not tags

This comment has been minimized.

@tomjoht

tomjoht Apr 4, 2017

Contributor

good catch. updated.

@tomjoht

tomjoht Apr 4, 2017

Contributor

good catch. updated.

@DirtyF

DirtyF approved these changes Apr 3, 2017

@tomjohnson1492 Just some comments, I might improve this tutorial later, but it's already a good start. Thanks for the effort.

Show outdated Hide outdated _tutorials/convert-html-site-to-jekyll.md
## 2. Establish the Default Layout
Find your HTML theme and save it as a default layout. If you're converting or cloning (with permission to do so) an existing site, you can right-click the page and view the source code. Copy and paste the source code into a file called `default.html` inside a folder called `_layouts`. This will be the layout template for your pages and posts.

This comment has been minimized.

@DirtyF

DirtyF Apr 3, 2017

Member

I understand it as an encouragement to check for the LICENSE if any.

@DirtyF

DirtyF Apr 3, 2017

Member

I understand it as an encouragement to check for the LICENSE if any.

Show outdated Hide outdated _tutorials/convert-html-site-to-jekyll.md
**_config.yml**
```yaml
markdown: kramdown

This comment has been minimized.

@DirtyF

DirtyF Apr 3, 2017

Member

This is already set by default:

"markdown" => "kramdown",

We could set website title or other useful setting to define though

@DirtyF

DirtyF Apr 3, 2017

Member

This is already set by default:

"markdown" => "kramdown",

We could set website title or other useful setting to define though

This comment has been minimized.

@tomjoht

tomjoht Apr 4, 2017

Contributor

In this tutorial, I'm not having users run jekyll new site because that ends up installing a default gem theme with its own styles and such. I have them just create the config file manually, so nothing would be populated by default in it.

@tomjoht

tomjoht Apr 4, 2017

Contributor

In this tutorial, I'm not having users run jekyll new site because that ends up installing a default gem theme with its own styles and such. I have them just create the config file manually, so nothing would be populated by default in it.

This comment has been minimized.

@ashmaroli

ashmaroli Apr 4, 2017

Member

I have them just create the config file manually, so nothing would be populated by default in it

The DEFAULTS Frank pointed to will be set automatically for an empty _config.yml

@ashmaroli

ashmaroli Apr 4, 2017

Member

I have them just create the config file manually, so nothing would be populated by default in it

The DEFAULTS Frank pointed to will be set automatically for an empty _config.yml

This comment has been minimized.

@DirtyF

DirtyF Apr 4, 2017

Member

I get you, but It's not related to the newcommand, Jekyll already sets some configuration defaults for you and use them when your run the build command. In theory you don't even need a _config.yml to build a jekyll site. Except when you want to override a default value, like sourceor permalink you don't need to write those keys in the config file. Convention over Configuration paradigm applies here.

@DirtyF

DirtyF Apr 4, 2017

Member

I get you, but It's not related to the newcommand, Jekyll already sets some configuration defaults for you and use them when your run the build command. In theory you don't even need a _config.yml to build a jekyll site. Except when you want to override a default value, like sourceor permalink you don't need to write those keys in the config file. Convention over Configuration paradigm applies here.

This comment has been minimized.

@tomjoht

tomjoht Apr 4, 2017

Contributor

ahh, I see now. Thanks for clarifying. I made an update to the commit that makes it clear that kramdown is a default setting.

@tomjoht

tomjoht Apr 4, 2017

Contributor

ahh, I see now. Thanks for clarifying. I made an update to the commit that makes it clear that kramdown is a default setting.

Show outdated Hide outdated _tutorials/convert-html-site-to-jekyll.md
Find your HTML theme and save it as a default layout. If you're converting or cloning (with permission to do so) an existing site, you can right-click the page and view the source code. Copy and paste the source code into a file called `default.html` inside a folder called `_layouts`. This will be the layout template for your pages and posts.
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 stripped out, since Jekyll handles only static content.

This comment has been minimized.

@DirtyF

DirtyF Apr 3, 2017

Member

Jekyll has its own templating system (Liquid) that allows to retrieve dynamic content.

@DirtyF

DirtyF Apr 3, 2017

Member

Jekyll has its own templating system (Liquid) that allows to retrieve dynamic content.

This comment has been minimized.

@tomjoht

tomjoht Apr 4, 2017

Contributor

updated

@tomjoht

tomjoht Apr 4, 2017

Contributor

updated

Show outdated Hide outdated _tutorials/convert-html-site-to-jekyll.md
When a layout specifies another layout, it means the content of this layout will be stuffed into the `{% raw %}{{ content }}{% endraw %}` tag of the layout specified in the front matter. In this case, the content from `index.md` will be pushed into the `{% raw %}{{ content }}{% endraw %}` tags in the `home` layout. Then the `home` layout will be pushed into the `{% raw %}{{ content }}{% endraw %}` tags of the `default` layout.
(If you don't specify a layout, `default` is used by default. Specifying it in the front matter tags is optional.)

This comment has been minimized.

@DirtyF

DirtyF Apr 3, 2017

Member

Good point, we can use {: .info } here to emphase.

@DirtyF

DirtyF Apr 3, 2017

Member

Good point, we can use {: .info } here to emphase.

This comment has been minimized.

@tomjoht

tomjoht Apr 4, 2017

Contributor

updated

@tomjoht

tomjoht Apr 4, 2017

Contributor

updated

Show outdated Hide outdated _tutorials/convert-html-site-to-jekyll.md
(If you don't specify a layout, `default` is used by default. Specifying it in the front matter tags is optional.)
By the way, the we've only scratched the surface of what you can do with `for` loops in retrieving posts. For example, if you want to display posts from a specific category, you can do so by adding a `categories` property to your post's front matter, and then looking in those categories. Further, you can limit the number of results by adding a `limit` property. Here's an example:

This comment has been minimized.

@DirtyF

DirtyF Apr 3, 2017

Member

By the way, the we've only

@DirtyF

DirtyF Apr 3, 2017

Member

By the way, the we've only

This comment has been minimized.

@tomjoht

tomjoht Apr 4, 2017

Contributor

updated

@tomjoht

tomjoht Apr 4, 2017

Contributor

updated

Show outdated Hide outdated _tutorials/convert-html-site-to-jekyll.md
```xml
---
layout: null

This comment has been minimized.

@DirtyF

DirtyF Apr 3, 2017

Member

layout: nil

@DirtyF

DirtyF Apr 3, 2017

Member

layout: nil

This comment has been minimized.

@tomjoht

tomjoht Apr 4, 2017

Contributor

updated

@tomjoht

tomjoht Apr 4, 2017

Contributor

updated

This comment has been minimized.

@tomjoht

tomjoht Apr 4, 2017

Contributor

Actually, when I use nil instead of null, Jekyll complains in the command line about not being able to find a layout with the name of nil. But it doesn't complain when it looks for null.

@tomjoht

tomjoht Apr 4, 2017

Contributor

Actually, when I use nil instead of null, Jekyll complains in the command line about not being able to find a layout with the name of nil. But it doesn't complain when it looks for null.

This comment has been minimized.

@ashmaroli

ashmaroli Apr 4, 2017

Member

layout: null is correct. A quick reference I could think of

@ashmaroli

ashmaroli Apr 4, 2017

Member

layout: null is correct. A quick reference I could think of

Show outdated Hide outdated _tutorials/convert-html-site-to-jekyll.md
<link rel="alternate" type="application/rss+xml" href="/feed.xml" title="{% raw %}{{ site.title }}{% endraw %}">
```
Note that if you're publishing your site on Github Pages, you can add a Github Pages gem called [`jekyll-feed`][jekyll-feed] to auto-generate your feed.

This comment has been minimized.

@DirtyF

DirtyF Apr 3, 2017

Member

jekyll-feed is a gem plugin that works without the need to use GitHub Pages

@DirtyF

DirtyF Apr 3, 2017

Member

jekyll-feed is a gem plugin that works without the need to use GitHub Pages

This comment has been minimized.

@tomjoht

tomjoht Apr 4, 2017

Contributor

updated

@tomjoht

tomjoht Apr 4, 2017

Contributor

updated

Show outdated Hide outdated _tutorials/convert-html-site-to-jekyll.md
</urlset>{% endraw %}
```
Note that if you're publishing your site on Github Pages, you can add a Github Pages gem called [`jekyll-sitemap`][jekyll-sitemap] to auto-generate your sitemap.

This comment has been minimized.

@DirtyF

DirtyF Apr 3, 2017

Member

same here jekyll-sitemap does not require for you to use GitHub Pages. I think what you mean it's that this gem is whitelisted by GitHub Pages.

@DirtyF

DirtyF Apr 3, 2017

Member

same here jekyll-sitemap does not require for you to use GitHub Pages. I think what you mean it's that this gem is whitelisted by GitHub Pages.

This comment has been minimized.

@tomjoht

tomjoht Apr 4, 2017

Contributor

updated

@tomjoht

tomjoht Apr 4, 2017

Contributor

updated

Show outdated Hide outdated _tutorials/convert-html-site-to-jekyll.md
When a layout specifies another layout, it means the content of the first layout will be stuffed into the `{% raw %}{{ content }}{% endraw %}` tag of the second layout. As an analogy, think of Russian dolls that fit into each other. Each layout fits into another layout that it specifies.
```
home --> default

This comment has been minimized.

@ashmaroli

ashmaroli Apr 3, 2017

Member

can you point me to the source_code for processing above home --> default

@ashmaroli

ashmaroli Apr 3, 2017

Member

can you point me to the source_code for processing above home --> default

This comment has been minimized.

@ashmaroli

ashmaroli Apr 3, 2017

Member

Thanks @DirtyF I now see that Tom was only illustrating the concept with an example of Russian Dolls fitting to each other (home --> default) and not setting a layout: home --> default as I saw it earlier... need to get some rest.....

@ashmaroli

ashmaroli Apr 3, 2017

Member

Thanks @DirtyF I now see that Tom was only illustrating the concept with an example of Russian Dolls fitting to each other (home --> default) and not setting a layout: home --> default as I saw it earlier... need to get some rest.....

This comment has been minimized.

@tomjoht

tomjoht Apr 4, 2017

Contributor

updated. I'll fix this confusion with a diagram instead. My arrow was a lame attempt at an illustration.

@tomjoht

tomjoht Apr 4, 2017

Contributor

updated. I'll fix this confusion with a diagram instead. My arrow was a lame attempt at an illustration.

Show outdated Hide outdated _tutorials/convert-html-site-to-jekyll.md
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 [filter tags](/docs/templates/) to prepend a site URL before path. For example, you could preface your stylesheet like this:

This comment has been minimized.

@ashmaroli

ashmaroli Apr 3, 2017

Member

Can we not mix two distinct entities here? filters and tags are two distinct functional entities in Liquid.

- [filter tags](/docs/templates/)
+ [URL filters](/docs/templates/#filters)
@ashmaroli

ashmaroli Apr 3, 2017

Member

Can we not mix two distinct entities here? filters and tags are two distinct functional entities in Liquid.

- [filter tags](/docs/templates/)
+ [URL filters](/docs/templates/#filters)

This comment has been minimized.

@tomjoht

tomjoht Apr 4, 2017

Contributor

updated

@tomjoht

tomjoht Apr 4, 2017

Contributor

updated

@tomjoht

This comment has been minimized.

Show comment
Hide comment
@tomjoht

tomjoht Apr 4, 2017

Contributor

I made the updates noted in previous reviews.

Note: I tried changing the file name from convert-html-site-to-jekyll.md to create-jekyll-theme.md, but I think this may have been a bad idea because Github wants to retain all the comments on the previous file and its name? I don't think my commit actually deleted/renamed the old file. It seemed to have just added another one. If I need to explicitly remove the convert-html-site-to-jekyll.md file, let me know. The create-jekyll-theme.md should replace it.

I added 2 other files in this commit -- an update to the list of items on the tutorials nav and an image.

Contributor

tomjoht commented Apr 4, 2017

I made the updates noted in previous reviews.

Note: I tried changing the file name from convert-html-site-to-jekyll.md to create-jekyll-theme.md, but I think this may have been a bad idea because Github wants to retain all the comments on the previous file and its name? I don't think my commit actually deleted/renamed the old file. It seemed to have just added another one. If I need to explicitly remove the convert-html-site-to-jekyll.md file, let me know. The create-jekyll-theme.md should replace it.

I added 2 other files in this commit -- an update to the list of items on the tutorials nav and an image.

@ashmaroli

This comment has been minimized.

Show comment
Hide comment
@ashmaroli

ashmaroli Apr 4, 2017

Member

I love the concept behind your illustration to explain nested layouts, but from a total-noob's point-of-view, I can't make sense out of it.. specifically, which layout is the default.html

Member

ashmaroli commented Apr 4, 2017

I love the concept behind your illustration to explain nested layouts, but from a total-noob's point-of-view, I can't make sense out of it.. specifically, which layout is the default.html

@tomjoht

This comment has been minimized.

Show comment
Hide comment
@tomjoht

tomjoht Apr 4, 2017

Contributor
Contributor

tomjoht commented Apr 4, 2017

@ashmaroli

This comment has been minimized.

Show comment
Hide comment
@ashmaroli

ashmaroli Apr 4, 2017

Member

Each layout does indicate the name of the layout directly on it. I'm not sure how to make it any clearer. If you have suggestions, let me know.

---
layout: default.html
---

indicates that this layout is a descendant of default.html i.e. its contents will be inserted into default.html
instead you could have the name either displayed as a caption underneath the boxes, or as a comment in the FrontMatter:

---
# _layouts/home.html

# contents of this layout will be injected into 'default.html'
layout: default
---
Member

ashmaroli commented Apr 4, 2017

Each layout does indicate the name of the layout directly on it. I'm not sure how to make it any clearer. If you have suggestions, let me know.

---
layout: default.html
---

indicates that this layout is a descendant of default.html i.e. its contents will be inserted into default.html
instead you could have the name either displayed as a caption underneath the boxes, or as a comment in the FrontMatter:

---
# _layouts/home.html

# contents of this layout will be injected into 'default.html'
layout: default
---
@tomjoht

This comment has been minimized.

Show comment
Hide comment
@tomjoht

tomjoht Apr 4, 2017

Contributor

thanks for the ideas. i'll see if i can work this into the graphic.

Contributor

tomjoht commented Apr 4, 2017

thanks for the ideas. i'll see if i can work this into the graphic.

@tomjoht

This comment has been minimized.

Show comment
Hide comment
@tomjoht

tomjoht Apr 4, 2017

Contributor

I updated the graphic about how layouts work to make it a little clearer. Hopefully this is better?

Contributor

tomjoht commented Apr 4, 2017

I updated the graphic about how layouts work to make it a little clearer. Hopefully this is better?

@DirtyF

This comment has been minimized.

Show comment
Hide comment
@DirtyF

DirtyF Apr 4, 2017

Member

Nice work @tomjohnson1492, let's add this tutorial and see of we have more feedback from the community 🌈

@jekyllbot: merge +docs

Member

DirtyF commented Apr 4, 2017

Nice work @tomjohnson1492, let's add this tutorial and see of we have more feedback from the community 🌈

@jekyllbot: merge +docs

@jekyllbot jekyllbot merged commit dede669 into jekyll:master Apr 4, 2017

2 checks passed

continuous-integration/appveyor/pr AppVeyor build succeeded
Details
continuous-integration/travis-ci/pr The Travis CI build passed
Details

jekyllbot added a commit that referenced this pull request Apr 4, 2017

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment