0

I am trying to contribute some documentation to an open source project, so I'm trying to locally preview the documentation pages, which are part of a github website. But, my code blocks are not being formatted correctly. I have created a minimal example:

_config.yml

markdown: kramdown
highlighter: rouge
kramdown:
  input: GFM
  hard_wrap: false
  parse_block_html: true
name: test

default.html

<!doctype html>
<html>
<body>{{ content }}</body>
</html>

auth.md

---
layout: default
---
## Authentication

Some description.

```scala
case class User(id: Long, name: String)
// defined class User
```

The resulting output from jekyll build is

<!doctype html>
<html>
<body><h2 id="authentication">Authentication</h2>

<p>Some description.</p>

<div class="language-scala highlighter-rouge"><span class="k">case</span> <span class="k">class</span> <span class="nc">User</span><span class="o">(</span><span class="n">id</span><span class="k">:</span> <span class="kt">Long</span><span class="o">,</span> <span class="n">name</span><span class="k">:</span> <span class="kt">String</span><span class="o">)</span>
<span class="c1">// defined class User
</span></div>
</body>
</html>

This results in one long line of unformatted code. On the github site (which you can see here http://http4s.org/docs/0.15/auth.html), the html has <pre> and <code> elements. Like this:

<div class="language-scala highlighter-rouge"><pre class="highlight"><code><span class="k">...

Since other people do not have this problem previewing the site locally, and I have the same trouble previewing http://typelevel.org/cats/, I assume it is some local configuration issue of some sort. However, I haven't been able to figure anything out. This is my first time using jekyll/kramdown, so I have no experience to leverage.

I have the github-pages gem installed, which has given me jekyll 3.3.1 and kramdown 1.11.1.

T Burnside
  • 121
  • 6
  • Have you tried with tildes ("~") instead of backticks ("`"). Not sure if it makes a difference, but it is what the kramdown docs show for code blocks. – TBB Nov 30 '16 at 03:33
  • Thanks for the suggestion, but that doesn't help. I guess the real issue is that it seems to work fine on github and for other users locally, but it does not work for me. – T Burnside Nov 30 '16 at 03:42
  • That is weird. It seems like it is parsing the contents of the block as markdown. Perhaps try removing 'parse_block_html: true`? – TBB Nov 30 '16 at 03:51
  • Aslo, see the last comment in the link discussion, showing a commit that may render some or all options as unnecessary - perhaps remove all the options or the hard wrap option or seomthing from your `_config` file. Link:https://github.com/github/pages-gem/issues/211 – TBB Nov 30 '16 at 03:56
  • You probably know this, but since your new to jekyll I'll say it anyway: You have to restart the server everytime you change the `_config` file. Sorry if I am stating the obvious. – TBB Nov 30 '16 at 04:01
  • 1
    I figured it out after digging through Github documentation. It was actually a version issue. There is a Gemfile and Gemfile.lock file in the repository. For one, they weren't being copied by the build process to the directory where the site was run from. And, I needed to install the bundler gem to install the dependencies with `bundle install`. And then run the site with `bundle exec jekyll serve`. This differs from the instructions on the repo's website. – T Burnside Nov 30 '16 at 04:36
  • Great. You should put that in as the answer for others who may see this, and perhaps also note it on the repo. – TBB Nov 30 '16 at 04:39

1 Answers1

2

In case it can help others out:

I figured it out after digging through Github documentation. It was actually a version and installed gems issue. There is a Gemfile and Gemfile.lock file in the repository. For one, they weren't being copied by the build process to the directory where the site was run from. And, I needed to install the bundler gem to install the dependencies with bundle install. And then run the site with bundle exec jekyll serve. This differs from the instructions on the repo's website.

T Burnside
  • 121
  • 6