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

Fixup tutorial on creating theme from existing HTML templates #6006

Merged
merged 12 commits into from Apr 9, 2017

Conversation

Projects
None yet
5 participants
@ashmaroli
Member

ashmaroli commented Apr 5, 2017

Found a few errors in the latest tutorial some of which, we missed while reviewing, the others became evident on reading the generated output.

/cc @jekyll/documentation @tomjohnson1492

@@ -147,7 +147,7 @@ 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.

This comment has been minimized.

@ashmaroli

ashmaroli Apr 5, 2017

Member

Jekyll doesn't automatically assign a layout. GitHub Pages does it via a plugin.

@ashmaroli

ashmaroli Apr 5, 2017

Member

Jekyll doesn't automatically assign a layout. GitHub Pages does it via a plugin.

@ashmaroli

This comment has been minimized.

Show comment
Hide comment
@ashmaroli

ashmaroli Apr 5, 2017

Member

@tomjohnson1492 i'd also like to make some edits to the graphic illustration. Will you be able to send the source file?

Member

ashmaroli commented Apr 5, 2017

@tomjohnson1492 i'd also like to make some edits to the graphic illustration. Will you be able to send the source file?

@tomjoht

This comment has been minimized.

Show comment
Hide comment
@tomjoht

tomjoht Apr 5, 2017

Contributor

Looks great. Thanks for making these edits to improve the content. This is one of the enjoyable parts about collaborating on documentation. Re the source file, I attached it here:
jekylllayoutconcept.ai.zip

You can add it to the project if you want, but as a binary file it won't play well in a repo. Also, note that this is an .ai file (Adobe Illustrator) so you'll need Illustrator or something else that can read .ai files. I can convert this to SVG if you prefer that format.

Contributor

tomjoht commented Apr 5, 2017

Looks great. Thanks for making these edits to improve the content. This is one of the enjoyable parts about collaborating on documentation. Re the source file, I attached it here:
jekylllayoutconcept.ai.zip

You can add it to the project if you want, but as a binary file it won't play well in a repo. Also, note that this is an .ai file (Adobe Illustrator) so you'll need Illustrator or something else that can read .ai files. I can convert this to SVG if you prefer that format.

@tomjoht

This comment has been minimized.

Show comment
Hide comment
@tomjoht

tomjoht Apr 5, 2017

Contributor

@ashmaroli In case you want SVG instead of AI, it's attached here: jekylllayoutconcept.svg.zip

Contributor

tomjoht commented Apr 5, 2017

@ashmaroli In case you want SVG instead of AI, it's attached here: jekylllayoutconcept.svg.zip

@ashmaroli

This comment has been minimized.

Show comment
Hide comment
@ashmaroli

ashmaroli Apr 5, 2017

Member

@tomjohnson1492 Thanks for the source files. I can work with AI.. no probs..

Member

ashmaroli commented Apr 5, 2017

@tomjohnson1492 Thanks for the source files. I can work with AI.. no probs..

@DirtyF

This comment has been minimized.

Show comment
Hide comment
@DirtyF

DirtyF Apr 5, 2017

Member

@ashmaroli Thanks for adapating the illustration to Jekyll's styleguide ❤️

If you're still working on this, I would like to change the title (and url) to something like "Convert an existing HTML template for Jekyll". Creating a Jekyll theme is the way you package then your files into a gem (it might be a good idea to link both notions btw).

Member

DirtyF commented Apr 5, 2017

@ashmaroli Thanks for adapating the illustration to Jekyll's styleguide ❤️

If you're still working on this, I would like to change the title (and url) to something like "Convert an existing HTML template for Jekyll". Creating a Jekyll theme is the way you package then your files into a gem (it might be a good idea to link both notions btw).

@DirtyF DirtyF added the documentation label Apr 5, 2017

@ashmaroli

This comment has been minimized.

Show comment
Hide comment
@ashmaroli

ashmaroli Apr 5, 2017

Member

@DirtyF How does the following sound?

Convert existing HTML Sites to Jekyll Templates
Member

ashmaroli commented Apr 5, 2017

@DirtyF How does the following sound?

Convert existing HTML Sites to Jekyll Templates
@tomjoht

This comment has been minimized.

Show comment
Hide comment
@tomjoht

tomjoht Apr 5, 2017

Contributor

That was actually similar to my original title. I had changed it due to a suggestion in an earlier review. I like the title you propose.

Contributor

tomjoht commented Apr 5, 2017

That was actually similar to my original title. I had changed it due to a suggestion in an earlier review. I like the title you propose.

@DirtyF

This comment has been minimized.

Show comment
Hide comment
@DirtyF

DirtyF Apr 5, 2017

Member

@ashmaroli 👍 fine by me, as long as we avoid the confusion with 💎 -based themes.

@tomjohnson1492 😖

Member

DirtyF commented Apr 5, 2017

@ashmaroli 👍 fine by me, as long as we avoid the confusion with 💎 -based themes.

@tomjohnson1492 😖

Show outdated Hide outdated docs/_tutorials/convert-existing-html-sites-to-jekyll-templates.md
* 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.
* Jekyll pushes the content from all pages and posts into the `{% raw %}{{ content }}{% endraw %}` tag in the layout specified (`default`) in the front matter tags.

This comment has been minimized.

@DirtyF

DirtyF Apr 5, 2017

Member

Technically content is a global variable, who acts as a placeholder .

@DirtyF

DirtyF Apr 5, 2017

Member

Technically content is a global variable, who acts as a placeholder .

This comment has been minimized.

@ashmaroli

ashmaroli Apr 6, 2017

Member

True. This prompts me to carve out a separate section:

## 2. Liquid Structure

The 3 basic pillars defining Liquid language are:
  * tags -- (say what they are and what they do in one-line)
  * filters -- (say what they are and what they do in one-line)
  * variables -- (say what they are and what they do in one-line)

Whatsay? Or is there an appropriate page already out there that I can simply link to?

@ashmaroli

ashmaroli Apr 6, 2017

Member

True. This prompts me to carve out a separate section:

## 2. Liquid Structure

The 3 basic pillars defining Liquid language are:
  * tags -- (say what they are and what they do in one-line)
  * filters -- (say what they are and what they do in one-line)
  * variables -- (say what they are and what they do in one-line)

Whatsay? Or is there an appropriate page already out there that I can simply link to?

Show outdated Hide outdated docs/_tutorials/convert-existing-html-sites-to-jekyll-templates.md
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 a Jekyll template 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.

This comment has been minimized.

@DirtyF

DirtyF Apr 5, 2017

Member

site -> site or template -> template but we don't convert a site into a template (rather to a set of templates and includes)

@DirtyF

DirtyF Apr 5, 2017

Member

site -> site or template -> template but we don't convert a site into a template (rather to a set of templates and includes)

This comment has been minimized.

@ashmaroli

ashmaroli Apr 6, 2017

Member

I agree.. I was really stuck as what this should be.. ultimately changed it to match the title I chose.

So what does this line finally say?

Understanding how to convert any site to Jekyll will open your world ...

?

@ashmaroli

ashmaroli Apr 6, 2017

Member

I agree.. I was really stuck as what this should be.. ultimately changed it to match the title I chose.

So what does this line finally say?

Understanding how to convert any site to Jekyll will open your world ...

?

This comment has been minimized.

@DirtyF

DirtyF Apr 6, 2017

Member

@ashmaroli What do you think of Understanding how to convert HTML pages into Jekyll templates ?

@DirtyF

DirtyF Apr 6, 2017

Member

@ashmaroli What do you think of Understanding how to convert HTML pages into Jekyll templates ?

This comment has been minimized.

@tomjoht

tomjoht Apr 6, 2017

Contributor

Re "Understanding how to ...", in general it's bad practice to use empty gerunds like "understanding" in task titles. Think of what users would type in Google to find the topic. Usually users type the task they're trying to accomplish, using the simple present tense. For example, "create jekyll site from html template" or something. I recommend that phrase: "Create a Jekyll site from an HTML template" or something similar.

@tomjoht

tomjoht Apr 6, 2017

Contributor

Re "Understanding how to ...", in general it's bad practice to use empty gerunds like "understanding" in task titles. Think of what users would type in Google to find the topic. Usually users type the task they're trying to accomplish, using the simple present tense. For example, "create jekyll site from html template" or something. I recommend that phrase: "Create a Jekyll site from an HTML template" or something similar.

This comment has been minimized.

@ashmaroli

ashmaroli Apr 6, 2017

Member

@tomjohnson1492 the above suggestion was not for a title but simply a sentence in the para under review

@ashmaroli

ashmaroli Apr 6, 2017

Member

@tomjohnson1492 the above suggestion was not for a title but simply a sentence in the para under review

This comment has been minimized.

@tomjoht

tomjoht Apr 6, 2017

Contributor

oh, my fault for misreading that. Sorry about that.

@tomjoht

tomjoht Apr 6, 2017

Contributor

oh, my fault for misreading that. Sorry about that.

Show outdated Hide outdated docs/_data/tutorials.yml
@@ -4,7 +4,7 @@
- navigation
- orderofinterpretation
- custom-404-page
- create-jekyll-theme
- convert-existing-html-sites-to-jekyll-templates

This comment has been minimized.

@DirtyF

DirtyF Apr 5, 2017

Member

Can we stay generic here? convert-site-to-jekyll

@DirtyF

DirtyF Apr 5, 2017

Member

Can we stay generic here? convert-site-to-jekyll

Show outdated Hide outdated docs/_tutorials/convert-existing-html-sites-to-jekyll-templates.md
@@ -1,25 +1,30 @@
---
layout: tutorials
permalink: /tutorials/create-jekyll-theme/
title: Create your first Jekyll theme
permalink: /tutorials/convert-existing-html-sites-to-jekyll-templates/

This comment has been minimized.

@DirtyF

DirtyF Apr 5, 2017

Member

same as above please let's keep this generic convert-site-to-jekyll

@DirtyF

DirtyF Apr 5, 2017

Member

same as above please let's keep this generic convert-site-to-jekyll

@DirtyF

DirtyF approved these changes Apr 5, 2017 edited

Great team effort here, I like this! 🙌

@DirtyF

This comment has been minimized.

Show comment
Hide comment
@DirtyF

DirtyF Apr 6, 2017

Member

@tomjohnson1492 I could not resist to make some edits. ✍️

Member

DirtyF commented Apr 6, 2017

@tomjohnson1492 I could not resist to make some edits. ✍️

@DirtyF

This comment has been minimized.

Show comment
Hide comment
@DirtyF

DirtyF Apr 9, 2017

Member

@jekyllbot: merge +docs

Member

DirtyF commented Apr 9, 2017

@jekyllbot: merge +docs

@jekyllbot jekyllbot merged commit 029b993 into jekyll:master Apr 9, 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 9, 2017

@ashmaroli ashmaroli deleted the ashmaroli:theme-tutorial-patch branch Apr 10, 2017

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