Keep whitespace in included html

Help
1

I’m using Jekyll to build a documentation website and I’ve run into an issue when including other HTML in Jekyll. Part of my documentation is built automatically from the source code (using odoc). This generates JSON files which contains metadata about each page and a fully rendered html content. I use a small ruby plugin to detect all those json files and generate a jekyll page for each.

These pages use a layout that looks like this:

---
layout: default
---

<div class="odoc">
  {{ page.odoc.content }}
</div>

My problem is that the {{ page.odoc.content }} doesn’t include the json string verbatim, it strips newlines and repeated spaces. How can I prevent this ?

This is an issue because odoc generates two separate code block styles:

  • One is for code blocks inside documentation comments, these are wrapped in <pre><code> blocks and are rendered correctly (whitespace preserved)
  • The other is for code from the source itself. These don’t use <pre> blocks, they are only rendered in <code> and use white-space: pre-wrap; to render. These are the blocks whose formatting breaks.

I’ve tried using {{ page.odoc.content | newlines_to_br }}, and it doesn’t help. For one, it breaks the first code block, whose newlines have now been doubled. Furthermore, while it does render newlines correctly for the second code block type, it doesn’t preserve indentation (multiple successive spaces are still replaced by a single space).

2

I found the culprit: it was compress html, automatically included by just-the-docs

With this identified, there are a number of ways to fix my issue:

  • The simplest: just add the following to _config.yml
    compress_html:
  blanklines: true
    with this compress html will only remove blank lines, which fixes my issue as there are no blank lines in the generated code blocks.
  • Use a page/layout that inherits from nothing for the relevant pages. This isn’t really satisfactory as it means copying the whole just-the-docs layout to your new layout.
  • Edit _layout/vendor/compress.html to allow for per page/layout configuration. I opened an issue which mentions the edits I performed to have a way to toggle it off or switch it to blanklines mode on a page/layout basis. See this commit for my implementation of it (Important files: _layout/vendor/compress.html and the frontmatter of _layout/odoc.html)