I've recently switched over to using Jekyll on Github Pages for my various blogs, and love that I can just push Markdown to Github and they handle the processing. I'd like to continue using it this way (rather than running Jekyll locally and just pushing the pre-generated site to Github), since the Github UI makes it easy to add and tweak posts if I'm not at my own machine.
There's just one thing I haven't been able to figure out: I can't get Markdown footnotes working. I'm using this style:
I bet you'd like more information about this sentence [^1].
[^1]: Well lucky for you, I've included more information in footnote form.
I did find one post (somewhere) that suggested enabling a footnotes extension for the redcarpet markdown processor, but this doesn't do it either:
markdown: redcarpet
redcarpet:
extensions: ["footnotes"]
Is there any way to use Markdown footnotes without pre-generating the static site before pushing it to Github?
I use kramdown for markdown parsing and it handles footnotes nicely.
Change this line in your _config.yml file:
markdown: redcarpet
to:
markdown: kramdown
As of Jekyll 3.0.0, kramdown is the default Markdown processor, so the example in OP's question now works out of the box. The pattern is:
Some text[^1].
Some other text[^2].
The identifier in the square brackets does not have to be numeric[^my_footnote].
[^1]: Some footnote.
[^2]: Other footnote.
[^my_footnote]: This also works fine.
Update 3rd Jan. 2020:
GitHub has its own markdown processor GFM, which is an extension of CommonMark. Both kramdown and GFM can be used to render GitHub Flavored Markdown.
Footnotes are not yet supported by GitHub Flavored Markdown, which means the above examples do not render correctly in the GitHub code repository.
Kramdown is still the default Markdown renderer for Jekyll. With kramdown, the above examples render correctly on sites based on GitHub Pages.
Redcarpet
When you want to use redcarpet there seems to be no convenient solution right now.
Although Redcarpet 3 supports footnotes with the syntax you've used, it is not included into Jekyll, because Redcarpet 3 removes Ruby 1.8 compatibility (source).
Solution 1: Use forked Redcarpet 2
See this solution by Jerod Santo:
Add a file called Gemfile to the root of your Jekyll folder with this content:
source "https://rubygems.org"
gem "jekyll"
gem "redcarpet", github: "triplecanopy/redcarpet"
or alternatively djui/redcarpet
Theny adjust your _config.yml to
markdown: redcarpet
redcarpet:
extensions: [footnotes]
Solution 2: Fork Jekyll and include Redcarpet 3
I don't know what's the easiest way to do this. Comments are welcome.
Maruku
Seems to support footnotes (source, source).
I found that plugin for jekyll Github orangejulius/jekyll-footnotes. May it solve the issue.
Also I read just today an blog post that Github improves the footnotes.
Related
I'm trying to create a github.io profile.
May I know the difference between of .md .html .rmd files?
For example, I see the same file name with different filetypes like
Readme.md vs Readme.html XXX.rmd vs XXX.html
github.io (aka Github pages) can create a website from either
html with optional css
Markdown files (.md and .rmd)
A combination of the above
It uses a set of tools called Jekyll and kramdown to translate markdown files into html to be displayed as part of the website.
Markdown files are a file format generally used for producing documentation in github on similar websites, and has a mopre streamlined syntax for that purpose than html. You can try it out at https://stackedit.io
The use of markdown for Github Pages is however completely optional and you may use only html if you wish. You can follow the guide at https://jmcglone.com/guides/github-pages show you how to make a github pages site with html. Stop when you get to the section Using Jekyll with GitHub Pages if you don't wish to incorporate any markdown.
i have been trying to create jekyll site and host on git-pages. Localy everything works fine. But on github-pages works only first pages and 10 newest blog post.
But after going to any of other pages like "Blogas" or "Straipniai" every link starts with 'localhost:4000' and naturaly breaks css, javascript...
And i am not sure where is problem, because everything is same even if i make change in /_includes/header.html site.url to site.baseurl.
Here is git-hub
And site
I think the problem is that you somehow have both a .md and an .html version of the same pages. The .html version you built locally and GH is preferring it. it has localhost in the urls so it won't work. Try deleting the .html files in those sub folders and see what happens. For example, delete the index.html file from invisibleghostt.github.io/blogas/ and see if that page is fixed.
No idea how you got those files in there, they should not be there.
Look, there are a few things you'd better fix on your _config.yml:
url: "http://codas.lt" # add the site url
gems: # remove `jekyll` from gems
- jekyll-sitemap
- jekyll-gist
- octopress
include: [".htaccess"] # remove this line (GitHub Pages does not support .htaccess)
The other thing is, you'll need to remove all the folders from the folder _posts, as explained here:
If you organized your categories as
/_posts/code/2008-12-24-closures.md, you will need to restructure your
directories to put the categories above the _posts directories, as
follows: /code/_posts/2008-12-24-closures.md.
You are probably working locally with a Jekyll version which diverges from GitHub Pages' (currently is Jekyll 3.0.3). That's why your site works locally and doesn't work there. To avoid that, build Jekyll with Bundler (a dependency manager). On this answer you can see how to do that, step-by-step.
Hope to have helped! :)
Note: If you get stuck in how to adapt your theme to work with GitHub Pages, you can try GitLab Pages, as you can easily set the Jekyll version you want to use to build your site. For example, this project builds the site with Jekyll 2.5.3.
I am editing my markdown in some online editor dillinger.io. Then copying the content into jekyll _posts. However, the jekyll is rendering on the browser differently that what I am seeing in above mentioned editor/github preview of the file.
The major problem I am facing is with the bullet points. I am not able to display bullet points with "*" or "-" markdown syntax. To display it using jekyll I need to use tag in markdown file. I have googled for long hours and used below configuration in _config.yml file to get the better output.
markdown: kramdown
kramdown:
input: GFM
But still it is not the one I am expecting. Below are the screenshots
Online editor and github preview are same as shown in the following URL -
But Jekyll is rendering as follows -
With the mentioned change in _config.yml file. It is better but still it does not display bullet points properly -
Some of the stackoverflow posts is saying that it is the issue with the default Jekyll markdown rendering engine.
Can you please suggest me what change do I need to make to get the same output as I see in github preview as mentioned in the following URL? -
The kramdown GFM parser only supports some Github Flavored Markdown options (see documentation)
In Jekyll you need two new lines before your list :
The list
- item 1
- item 2
md file with a link to Folder/file.md
When jekyll generates the index the link to the file is still folder/file.md and so doesn't connect to the generated file.html. Can jekyll replace links in markdown with their corresponding html files?
I really want to to maintain my folder structure (7 or so subfolders, each with 3 markdown files).
The answer since December 2016 is to use the jekyll-relative-links plugin.
It is a white-listed plugin if you are hosting on GitHub pages so you probably already have it.
If you are not using GitHub pages you will need the following installation instructions (from the README):
1.Add the following to your site's Gemfile:
gem 'jekyll-relative-links'
2.Add the following to your site's config file:
gems:
- jekyll-relative-links
The tag you're looking for is {% link %} and it arrived in 2016.
If you had {% link _funkyCollection/banjo.md %} it would generate the right path to the output file funkyCollection/banjo.html, or funkyCollection/banjo/index.html, or whatever, wherever it ends up being.
This is what I did to solve this problem with jekyll 3.8.5.
For link in root directory: /file.md
---
layout: page
title: Root File
permalink: /file/
---
This file is in root directory.
For link in subdirectory: /folder/file.md
---
layout: page
title: SubDir File
permalink: /folder/file/
---
This file is in sub-directory.
Now to link these file:
[Root File]({{site.baseurl}}/file/))
[Sub Dir File]({{site.baseurl}}/folder/file/)
Hope this helps someone.
i've written a simple plugin to solve this. put this in _plugins/, and make links refer to the *.md files (so github rendering linking works); if you build it with jekyll (when you are able to run plugins) the links are changed to *.html. since github doesn't run plugins, this isn't applied.
module ChangeLocalMdLinksToHtml
class Generator < Jekyll::Generator
def generate(site)
site.pages.each { |p| rewrite_links(site, p) }
end
def rewrite_links(site, page)
page.content = page.content.gsub(/(\[[^\]]*\]\([^:\)]*)\.md\)/, '\1.html)')
end
end
end
it's not perfect (i'm sure you could fool the regex) but it has been good enough for my purpose.
A Folder/file.md page will result in creation of a _site/Folder/file.html page.
So when your link to this page it's [Link to page]({{site.baseurl}}/Folder/file.html) not [Link to page]({{site.baseurl}}/Folder/file.md).
Jekyll will never rewrite file.md to file.html in url. So you have to set your links targets yourself to the resulting page.url which is usually a html file but can be css, je, json, ...
If you use permalink: /folder/folder/ in any file.md, it will generate a /folder/folder/index.html file which can be reached with [Link to page]({{site.baseurl}}/folder/folder/)
I've run into this and written a basic Jekyll/Kramdown plugin. It's less likely to break than the regular expression approach.
As long as your link doesn't start with http:// or something like it, and ends with .md, it will convert links to their lowercased and hyphenated names.
Of course, you could always modify the behavior to fit your needs.
using jekyll 2.0.3,
I initially configured _config.yml with
markdown: kramdown
and I was able to add a table of contents as follows, in my example.md:
---
layout: page
title: Sample
---
{:toc}
## section 1
## section 2
however, I switched to redcarpet, see _config.yml:
markdown: redcarpet
redcarpet:
extensions: ["no_intra_emphasis", "fenced_code_blocks", "autolink", "strikethrough", "superscript", "with_toc_data"]
and now {:toc:} does not work.
The documentation of redcarpet v2.2.2 (used by jekyll 2.0.3):
https://github.com/vmg/redcarpet/blob/v2.2.2/README.markdown#and-its-like-really-simple-to-use
mentions :with_toc_data, but I don't where/how to use this.
how can i display the table of contents using redcarpet?
The problem here is that :with_toc_data is an option for an instance of the redcarpet renderer, and not a configuration extension.
Unfortunately, Jekyll doesn't seem to expose this renderer option, so I don't think you'll be able to use it. The docs say:
no renderer options aside from smart can be specified in Jekyll.
But you can use a table of contents jekyll plugin instead. A quick search returns a number of available options, and one is linked from the official Jekyll site.
Maybe this should work. Mention this in the _config.yml file.
markdown: redcarpet
redcarpet:
extensions: [with_toc_data]
I'm using markdown on my blog along with JQuery and a js file. This is how it looks like.
Here is the detailed guide on how to do it - Jekyll TOC