Problem
Problem: I can't get a local build of my GitHub hosted website. My gh-pages branch on my local clone of my GitHub repo does not build right.
Specifically, markdown files don't build to the _site folder as html unless they start with the YAML frontmatter demarcation (--- newline ---), and when I serve them on localhost they don't pickup any CSS, I can't really preview what it will look like on GitHub. If the frontmatter demarcation is not in the markdown file it is copied to the _site folder as markdown.
You can see below I have two markdown files ideas.md and local-jekyll-build-theme-trouble.md.
ideas.md has the frontmatter things and builds as an html file that won't preview with any theme.
local-jekyll-build-theme-trouble.md doesn't have the frontmatter and 'builds' as markdown and 404s when I try to hit it in the browser (unless I add the .md extension in the URL, boo)
It doesn't make any difference if I have committed changes or not. It doesn't matter if I run jekyll via 'bundle exec' or not. I don't get any errors from jekyll (even when using the --trace option)
In Contrast...
When I push to GitHub, both pages seem to work properly. I can go to https://breedlovedesign.github.io/ideas/local-jekyll-build-theme-trouble without putting .md in the URL and https://breedlovedesign.github.io/ideas/ serves index.html fine. Both get all the lovely theme CSS as specified in my config.
I had assumed that both files were being converted to html but I double-checked and the _site folder on GitHub also has index.html and local-jekyll-build-theme-trouble.md.
_config.yml
theme: jekyll-theme-minimal
System Info
MacOS 10.15.6
Ruby Version
~/.../devo/ideas on gh-pages*
$ rbenv version
2.6.5 (set by /Users/johnbreedlove/Sync/devo/ideas/.ruby-version)
Gemfile
gem "github-pages", "~> 209"
Jekyll Build Output
~/.../devo/ideas on gh-pages*
$ bundle exec jekyll serve
Configuration file: /Users/johnbreedlove/Sync/devo/ideas/_config.yml
Source: /Users/johnbreedlove/Sync/devo/ideas
Destination: /Users/johnbreedlove/Sync/devo/ideas/_site
Incremental build: disabled. Enable with --incremental
Generating...
done in 0.616 seconds.
Auto-regeneration: enabled for '/Users/johnbreedlove/Sync/devo/ideas'
Server address: http://127.0.0.1:4000
Server running... press ctrl-c to stop.
Directory Structure
~/.../devo/ideas on gh-pages*
$ tree
.
├── Gemfile
├── Gemfile.lock
├── _config.yml
├── _site
│ ├── assets
│ │ ├── css
│ │ │ └── style.css
│ │ ├── fonts
│ │ │ ├──...
│ │ ├── img
│ │ │ └── logo.png
│ │ └── js
│ │ └── scale.fix.js
│ ├── index.html
│ └── local-jekyll-build-theme-trouble.md
├── index.md
└── local-jekyll-build-theme-trouble.md
10 directories, 30 files
Contents of /index.md
---
---
# icanhaz themes pls?
must I use YAML frontmatter?
Yes, you must use the YAML front matter. It is made explicit in the jekyll documentation.
Any file that contains a YAML front matter block will be processed by Jekyll as a special file. The front matter must be the first thing in the file and must take the form of valid YAML set between triple-dashed lines.
If you want to use Liquid tags and variables but don’t need anything in your front matter, just leave it empty! The set of triple-dashed lines with nothing in between will still get Jekyll to process your file.
If it works in GitHub Pages, I assume that it does a little preprocessing of its own. But for Jekyll alone, files without front matter are left as they are.
Related
I am trying to setup a template Jekyll project with the structure below. The goal is to reuse all markdown files in the project while being the least intrusive, keeping all custom layouts and configurations in a single folder.
.
├── README.md # some new project file stay in the roots
├── about.md # some new project file stay in the roots
├── docs # folder containing pages
│ └── assets
│ └── index.html # generated from README.md
│ └── about.html # generated from about.md
│ └── ...
├── jekyll # folder containing all jekyll specific files
│ └── _layout
│ └── assets
│ └── _config.yml
│ └── ...
To make this work, I'm running Jekyll from the /jekyll folder using the following configurations.
theme: jekyll-theme-cayman
source: ./..
destination: ./../docs
include:
- "./_layout"
- "./assets"
exclude:
- "./"
Here comes my problem: when I do this Jekyll ignores my custom layout. Could anyone help me understanding this problem?
P.S.: I'd prefer not to publish my custom layout as a new theme entirely.
I'm trying to accomplish the task of linking to files within a collection from a post on a Jekyll site. However, I'm having an issue that relates to the collection having subdirectories, and those subdirectories having spaces in their names.
Here's a simplified example of how my site source is layed out:
├── 404.html
├── about.md
├── _config.yml
├── Gemfile
├── Gemfile.lock
├── index.md
├── _labs
│ └── Lab 01 Introduction
│ └── PS01 source.html
├── _posts
│ └── 2020-01-01-test_post.md
The post 2020-01-01-test_post.md contains the following markdown:
---
layout: post
title: "Introduction"
author: "Will Hopper"
---
[Link]({{ site.baseurl }}{% link _labs/Lab 01 Introduction/PS01 source.html %})
So far so good, and running jekyll serve succeeds just fine, meaning it can find the linked file at build time. The issue arises later, with the way jekyll has handled the spaces in the Lab 01 Introduction directory. Here is the contents of the _site folder after building:
└── _site
├── 404.html
├── about
│ └── index.html
├── assets
│ ├── main.css
│ └── minima-social-icons.svg
├── feed.xml
├── index.html
├── labs
│ └── Lab%2001%20Introduction
│ └── PS01 source.html
└── posts
└── test_post.html
As you can see, the spaces in the filename have been replaced with the URL encoded escapes, %20. As a result, the link in the post 404's.
I tried replacing the "raw" name of the folder with the URL encoded output, i.e., I tried {% link _labs/Lab%2001%20Introduction/PS01 source.html %} but now the site fails to build with Liquid Exception: Could not find document.
This HTML file is effectively a static file (i.e., it has no front matter). And curiously, Jekyll seems to leave spaces in the filenames alone!
Any ideas on what I could do to stop the spaces in my directory names from being URL encoded when the site is built?
I have the following file structure in my Jekyll project:
├── _articles
│ ├── bar
│ │ └── widget.md
│ ├── bar.md
│ └── phone.md
└── foo.md
See here: https://github.com/janpio/jekyll-test
_articles is a collection that is defined in _config.yml:
collections:
articles:
title: Articles
output: true
permalink: :path
On Github Pages this is built into these URIs:
https://janpio.github.io/jekyll-test/bar/widget
https://janpio.github.io/jekyll-test/bar
https://janpio.github.io/jekyll-test/phone
https://janpio.github.io/jekyll-test/foo/
See here: https://janpio.github.io/jekyll-test/
That is all fine and as expected.
But when I bundle exec jekyll s this project locally1 it doesn't work the same way. I get the expected URIs:
http://127.0.0.1:4000/bar/widget
http://127.0.0.1:4000/bar
http://127.0.0.1:4000/phone
http://127.0.0.1:4000/foo/
But the problem is that #2 gets redirected to 127.0.0.1:4000/bar/ and shows a directory listing instead of the actual page!
Looking at _site this is the file structure that is generated:
├── bar
│ └── widget.html
├── bar.html
├── foo.html
├── index.html
└── phone.html
So I can access bar.md at http://127.0.0.1:4000/bar.html.
How can I fix this?
1 My Gemfile is so the environment should be identical to Github Pages: https://github.com/janpio/jekyll-test/blob/master/Gemfile
Update for Jekyll 3.6.x
The 3.6.0 Jekyll release changed this behaviour:
Fix serving files that clash with directories (#6222) (#6231)
Unfortunately, these changes didn't really fix the problem but replace it with a less serious one: The link now doesn't show the directory listing any more but the correct page, but the path is still different in that it adds the / at the end. Unfortunately as a regression bar/widget doesn't render the correct content any more but shows bar.md.
These are the first solutions that come to my mind:
Stop using 'pretty URLs'
Use only index.md files (each of them in a seperate folder)
Prevent naming collisions between folders and files
Create an index.html file in the bar folder that redirects to bar.html (although that might create a redirect loop)
Update for Jekyll 3.7.x
The 3.7.0 Jekyll release included a PR that should fix this problem:
return correct file in dir if dir has same name as file
I have a Jekyll blog and some of the raw posts have some additional files at the same level with the markdown file. For example:
.
├── _posts
├── first-post
├── 2007-10-29-first-post.md
└── download.zip
How can I and up with a generated structure such as
.
├── _sites
├── first-post
├── index.html
└── download.zip
The download.zip file needs to be in the same location as its dependent post (I cannot use any includes or other redirect tricks)
Try this jekyll-postfiles which is:
A Jekyll plugin that copies static files from the _posts to the _site folder
Note: I may have hit an edge case for Jekyll running in a Linux for Windows 10 environment. The same data used on pure Windows or in pure Linux work as expected (after the modifications following #marcanuy's answer). I will be back after more testing.
I created a new site via
jekyll new myblog --blank
This created the expected structure in myblog. I added a template _layouts/docs.html
<h1>hello world</h1>
{{ content }}
I then created a _posts/hello.md file:
---
title = the hello world page
layout = docs
---
# this is a hello world page
Hello world everyone
After running
# jekyll build
Configuration file: none
Source: /root/myblog
Destination: /root/myblog/_site
Incremental build: disabled. Enable with --incremental
Generating...
done in 0.03 seconds.
Auto-regeneration: disabled. Use --watch to enable.
my _site folder is empty, except for an index.html file copied from the root of my blog (copied verbatim - this is the content I put in index.html in the root)
Why isn't hello.html generated? I expected it to contain
<h1>hello world</h1>
<h1>this is a hello world page</h1>
Hello world everyone
There are two problems that makes jekyll not build the "hello" page:
filename
if you put hello.md inside the _posts folder, then the correct filename should contain post's date like: 2017-05-21-hello.md
Then it will be available:
.
├── _drafts
├── index.html
├── _layouts
│ └── docs.html
├── _posts
│ └── 2017-05-21-hello.md
└── _site
├── hello.html
└── index.html
Another approach is to publish it as a page:
in /hello.md, i.e.: at root level (not inside /_posts)
.
├── _drafts
├── hello.md
├── index.html
├── _layouts
│ └── docs.html
├── _posts
└── _site
├── hello.html
└── index.html
frontmatter
The other problem is the syntax of the front matter of hello.md, each attribute should be defined with : instead of =:
---
title: the hello world page
layout: docs
---
# this is a hello world page
Hello world everyone