Github pages cannot display markdown correctly

问题:

I am using github pages + jekyll to establish my blog.

It worked properly before pushed my latest commit. This commit adds a cname file and just edits some words without any alterations over the architecture of my site.

-    <h3 class="description">aaaaaaaaaa</h3>
+    <h3 class="description">bbbbbbbbbb</h3>

After that markdown does not appear properly.

When I write #head1. It does not appear title head1, it just appears #head1 directly.

However, if I use jekyll serve build in localhost:4000, it appears correctly.

This is my _config.yml:

markdown: kramdown
markdown_ext: markdown,mkd,mkdn,md
textile_ext: textile
highlighter: pygments

Any ideas what has been causing this error?

回答1:

UPDATED!

This is most likely due to Jekyll 3 upgrade on GitHub Pages.

From May 1st 2016 on, GitHub will not support rdiscount nor redcarpet anymore. Also, since February 1st, GitHub Pages only supports rouge:

Starting May 1st, 2016, GitHub Pages will only support kramdown, Jekyll's default Markdown engine.

GitHub Pages now only supports Rouge.

You can check this out here.

In order to deal with it, proceed as the following:

First, try as explained on this answer. Instead of #Heading you'll write # Heading.

Second, adjust your _config.yml: change highlighter and markdown for

highlighter: rouge
markdown: kramdown
kramdown:
  input: GFM

Third, to build your site locally, use Bundler, the method recommended by GitHub:

1. Install Bundler:

   gem install bundler
   

2. Then run bundle update - this will update all your gems, including github-pages, if you already have this gem installed locally.

3. Then, create a Gemfile (leave it without any file extension) with the following content:

   source 'https://rubygems.org' 
   gem 'github-pages'
   

Save it to your project's root.

4. Then, run bundle install on your project. This will create a file called Gemfile.lock and will install all required gems and their dependencies.

5. Finally, run bundle exec jekyll serve --watch and you'll be able to view your website locally exactly as you'll view online (when hosting on GitHub).

You should be OK by then!

---

PS. If your project needs more gems, as jekyll-paginate or jekyll-mentions, you'll need to add them to the Gemfile, for example:

source 'https://rubygems.org' 
gem 'github-pages'
gem 'jekyll-paginate'

Also, add them to your project's _config.yml:

gems:
  - jekyll-paginate
  - jekyll-mentions

Here you'll see a list of gem versions currently supported by GitHub Pages. Here you read about Upgrading Jekyll 2 to 3.

Hope to have helped!

回答2:

A slight observation running my own Jekyll powered github pages blog,

A space between the # representing the heading size, and the heading text is important otherwise the markdown will not display as intended. Therefore with your example, I would display my markdown heading as,

# Zookeeper Atomic Broadcast for heading 1

## Zookeeper Atomic Broadcast for heading 2

### Zookeeper Atomic Broadcast for heading 3

#### Zookeeper Atomic Broadcast for heading 4

##### Zookeeper Atomic Broadcast for heading 5

回答3:

GitHub support markdown as well jekyll.
First of all rename your file with the .md extension

If you have .nojekyll in your folder it will disable njekyll.

Verify that you don't have this is your folder.

---

Read the docs && GitHub relevant doc on how to prepare and deploy

---

Running Jekyll

Use the command git checkout to switch to the default branch that the GitHub Pages build server uses to generate your site. The default branch you switch to depends on the type of GitHub Pages site you're building.

For Project Pages sites, switch to gh-pages. For User Pages or Organization Pages sites, switch to master. For more information, see "User, Organization, and Project Pages".

Use the command bundle exec jekyll serve in the root of your repository to run the GitHub Pages build server with Bundler.

bundle exec jekyll serve Navigate to http://localhost:4000 to see your local site.