Please tell me how to create a basic Jekyll site. I am especially confused about the file _config.yml and the YAML front matter.
I don't quite understand the wording of you questions, but I'll take a shot. I'm guessing you are referring to one of two things. Either the config file or the YAML front matter. Whichever one, see below for a basic primer to get a jekyll site up and running. It shows the usage of both in context.
In an empty directory, create the following:
A new directory named _layouts.
A new directory named _posts.
A new directory named _site.
A file named index.md with the following content:
---
layout: default
---
# My Jekyll site
Welcome to my Jekyll site
(Note: the "layout: default" surrounded by the two lines of dashes is the YAML Front Matter. Specifying "default" means that jekyll will use the "default.html" file in the _layouts directory listed below.)
A file named _config.yml with the following default content:
safe: false
auto: false
server: false
server_port: 4000
base-url: /
source: .
destination: ./_site
plugins: ./_plugins
future: true
lsi: false
pygments: false
markdown: maruku
permalink: date
maruku:
use_tex: false
use_divs: false
png_engine: blahtex
png_dir: images/latex
png_url: /images/latex
rdiscount:
extensions: []
kramdown:
auto_ids: true,
footnote_nr: 1
entity_output: as_char
toc_levels: 1..6
use_coderay: false
coderay:
coderay_wrap: div
coderay_line_numbers: inline
coderay_line_numbers_start: 1
coderay_tab_width: 4
coderay_bold_every: 10
coderay_css: style
There are two more files you'll want to create for the example,
Inside the "_layouts" directory, a file named default.html with the following:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html lang="en">
<head>
<meta charset="utf-8">
<title>My Jekyll Site</title>
</head>
<body>
<!-- This will be replaced with your content -->
{{ content }}
</body>
</html>
Inside the "_posts" directory, a file named 2011-07-29-my-first-jekyll-post.md with the following:
---
layout: default
---
# My First Jekyll Post
The quick brown fox jumps over the lazy dog.
(Note: Once again, the "layout: default" surrounded by the two lines of dashes is the YAML Front Matter and specifies that "default.html" will be used for the template.)
At this point the directory structure should look like this:
./_config.yml
./_layouts
./_posts
./_posts/2011-07-29-my-first-jekyll-post.md
./_site
./index.md
Once all that is setup, from the command line go to the directory that has the index.md file in it and run jekyll. You should see a quick report like:
Configuration from /some-path/_config.yml
Building site: . -> ./_site
Successfully generated site: . -> ./_site
Two output file will have been created:
./_site/index.html
./_site/2011/07/29/my-first-jekyll-post.html
Those files correspond to the two markdown files after the were transformed to HTML and dropped into the default.html wrapper replacing the "{{ content }}" string.
That should get your started with the basics.
Related
I have simple jekyll site. Every post in _posts has paramter author in it's front matter:
---
layout: post
title: my title
author: John Doe
---
...
How should I set permalink in _confing.yml if i want it to be /author/title/?
For example post above would have permalink:
mysite.com/john-doe/my-title/
Thank you for help.
I solved this using jekyll_custom_permalink plugin.
Installation
Add the plugin to your site's Gemfile:
group :jekyll_plugins do
# your other jekyll plugins...
gem 'jekyll_custom_permalink', '~> 0.0'
end
Then run
$ bundle install
Usage
Lets assume that you have some options for your collection "projects" defined in _config:
collections:
projects:
output: true
permalink: projects/:title/
You would like to use custom Front Matter in the paths of your projects. For example, it would be great to be able to include the Front Matter variable type in the links to your projects, which is defined in every file belonging to the "projects" collection.
---
layout: page
type: python
title: MyAwesomeProject
---
Some content
You can use the type variable in your permalink by first adding it to an array of custom permalink placeholders for the collection, and then adding the placeholder to the permalink setting prefixed with a : like every other Jekyll placeholder.
collections:
projects:
output: true
custom_permalink_placeholders: ["type"]
permalink: projects/:type/:title/
These settings lead to the "project" page, shown above, to be live at /projects/python/MyAwesomeProject.
SOURCE: https://github.com/NiklasEi/jekyll_custom_permalink/blob/master/README.md
I'm unable to see the index.html get rendered with jekyll's front matter. In fact, the front matter is all I see on the webpage.
Here is the folder layout:
and the _config.yml:
title: badabing badaboom
email: xyz#gmail.com
description: tbd
#baseurl: "" # the subpath of your site, e.g. /blog
url: "" # the base hostname & protocol for your site, e.g. http://example.com
twitter_username:
github_username:
encoding: utf-8
# Build settings
theme: jekyll-theme-clean-blog
plugins:
- jekyll-feed
remote_theme: StartBootstrap/startbootstrap-clean-blog-jekyll
# Exclude from processing.
# The following items will not be processed, by default.
# Any item listed under the `exclude:` key here will be automatically added to
# the internal "default list".
#
# Excluded items can be processed by explicitly listing the directories or
# their entries' file path in the `include:` list.
Any ideas on how I could fix this, or what I should look into?
My god... *facepalm
I just needed to get rid of .nojekyll
GitHub Pages will use Jekyll to build your site by default. If you
want to use a static site generator other than Jekyll, disable the
Jekyll build process by creating an empty file called .nojekyll in the
root of your publishing source, then follow your static site
generator's instructions to build your site locally.
I have created a Gulp plugin called php-include-html, which scans php files in Gulp and processes include and require statements to inline HTML snippets.
The snippet of the gulpfile looks like this...
var gulp = require("gulp");
var pump = require("pump");
var phpinc = require("php-include-html");
gulp.task("php",function(cb) {
pump([
gulp.src("*.php"),
phpinc({verbose:true}),
gulp.dest("build")
],cb);
});
This is a snippet from the php file before processing...
<!DOCTYPE html>
<html lang="en-gb">
<head>
<title>Emma Malik's Official Website - Legal</title>
And here's the same snippet after processing...
<!DOCTYPE html>
<html lang="en-gb">
<head>
<title>Emma Malik&s Official Website - Legal</title>
As you can see, the apostrophe has been HTML encoded. However, it doesn't seem to be all ampersands, just some of them, and some other characters as well, such as > to > but again, not all of them.
All the way through my plugin, this remains an apostrophe, it seems to be the gulp.dest rewriting the file which somehow converts it.
Things I've tried...
Stripping the UTF-8 BOM from the source file (strip-bom and
strip-bom-buf)
Adding the UTF-8 BOM to the destination file (gulp-header)
Using string manipulation instead of String.replace
Converting the destination contents to UTF-8 (gulp-convert-encoding)
Decoding after my plugin before gulp.dest (gulp-html-entities)
Using vinyl-file
Has anyone seen anything like this before, or know how to fix it?
False alarm, it turns out that it is actually the "gulp-sri-hash" plugin, which runs after mine, which is doing this. I need to investigate further as to what exactly is causing this, but at least I've figured out it's not me!
There are so many posts describing this same error, and I have tried to read them all to find out exactly what is causing my error.
I have tried mangling this file eleven different ways, even reverting it back to the original file - still no luck. What am I missing?
The error is supposedly on "line 3 column 22" - which does not exist. I have no jekyll parser on the client side, everything is being handled through GitHub Pages.
https://github.com/drovani/drovani.github.io/commits/master/_config.yml
#
# This file contains configuration flags to customize your site
#
# Name of your site (displayed in the header)
name: "Rovani in C#"
# Short bio or description (displayed in the header)
description: "Ostinato, Pensato, Scordatura"
# URL of your avatar or profile pic (you could use your GitHub profile pic)
avatar: https://avatars3.githubusercontent.com/u/898478
#
# Flags below are optional
#
# Includes an icon in the footer for each username you enter
footer-links:
dribbble:
email: dev#rovani.net
facebook:
flickr:
github: drovani
instagram:
linkedin:
pinterest:
rss: # just type anything here for a working RSS icon
twitter: davidrovani
stackoverflow: "users/28310/drovani"
youtube: # channel/<your_long_string> or user/<user-name>
googleplus: # anything in your profile username that comes after plus.google.com/
# Enter your Disqus shortname (not your username) to enable commenting on posts
# You can find your shortname on the Settings page of your Disqus account
disqus: drovani
# Enter your Google Analytics web tracking code (e.g. UA-2110908-2) to activate tracking
google_analytics: UA-82341148-1
# Your website URL (e.g. http://barryclark.github.io or http://www.barryclark.co)
# Used for Sitemap.xml and your RSS feed
url:
# If you're hosting your site at a Project repository on GitHub pages
# (http://yourusername.github.io/repository-name)
# and NOT your User repository (http://yourusername.github.io)
# then add in the baseurl here, like this: "/repository-name"
baseurl: ""
#
# !! You don't need to change any of the configuration flags below !!
#
permalink: /:title/
# The release of Jekyll Now that you're using
version: v1.2.0
# Jekyll 3 now only supports Kramdown for Markdown
kramdown:
# Use GitHub flavored markdown, including triple backtick fenced code blocks
input: GFM
# Jekyll 3 and GitHub Pages now only support rouge for syntax highlighting
syntax_highlighter: rouge
syntax_highlighter_opts:
# Use existing pygments syntax highlighting css
css_class: 'highlight'
# Set the Sass partials directory, as we're using #imports
sass:
style: :expanded # You might prefer to minify using :compressed
# Use the following plug-ins
gems:
- jekyll-sitemap # Create a sitemap using the official Jekyll sitemap gem
- jekyll-feed # Create an Atom feed using the official Jekyll feed gem
# Exclude these files from your production _site
exclude:
- Gemfile
- Gemfile.lock
- LICENSE
- README.md
- CNAME
Instead of the issue being in the _config.yml file, it was in a completely different file altogether. So, if you get this error message from building a github-pages Jekyll page, don't assume that it is in the only "YAML" file. Search any new file that you have added for a Line 3 Column 22 and that will track down the error.
In my case, it was a title for a post in the front matter had a colon with a space after it - which I needed to put double-quotes around.
I have a markdown file as follows:
---
title: My Page
categories:
- first
- second
---
In my _config.yml file, I set the permalink to /:categories/:title.html
So when I generate the site, the permalink ends up being /first/second/title.html, whereas
I was hoping Jekyll would create /first/title.html and /second/title.html
Is there a way to do this without custom plugins?
Cheers
The easiest and to me best way is to define the permalink via frontmatter. This is also great for search engine optimization. First you tell Jekyll via _config.yml how Jekyll should build the links if you forget to set it via frontmatter:
_config.yml
# Build settings
permalink: /:categories/:title/
Define a permalink...
2014-10-17_my_post.md
---
layout: post
title: 'Post with permalink'
permalink: /this-is-the-unique-permalink/
---
My Post
According to these docs, it looks like each Jekyll page can only have one category. categories is kind of a misnomer, because you're really defining a "category hierarchy" - like a file path - so the post really resides in a single (sub)category. In this limited sense, you can't do what you want with vanilla Jekyll.
However, Jekyll will process files just sitting around in any directory that doesn't start with an underscore and it follows symlinks. So, for example, if you make directories for each category and place your page in one of them, you can create symlinks to any number of other "categories".
mkdir first second
touch first/page.md
ln -s ../first/page.md second/