mirror of
https://github.com/snachodog/just-the-docs.git
synced 2025-04-22 11:02:24 -06:00
61053f677b
The additions to `_config.yml` go together with the changes to `code.scss`, to facilitate adjusttments by users. See `docs/linenos-test` for the details. The CSS code has been significantly refactored and simplified, and seems to produce sensible results (at least on Safari and Firefox).
124 lines
3.0 KiB
Markdown
124 lines
3.0 KiB
Markdown
---
|
|
layout: default
|
|
title: Markdown line number test
|
|
nav_order: 999
|
|
---
|
|
|
|
# Configuration options
|
|
|
|
The default settings for HTML compression are incompatible with the HTML
|
|
produced by Jekyll (4.1.1 or earlier) for line numbers from highlighted code
|
|
-- both when using Kramdown code fences and when using Liquid highlight tags.
|
|
|
|
To avoid non-conforming HTML and unsatisfactory layout, HTML compression
|
|
can be turned off by using the following configuration option:
|
|
|
|
```yaml
|
|
compress_html:
|
|
ignore:
|
|
envs: all
|
|
```
|
|
|
|
When using Kramdown code fences, line numbers are turned on globally by the
|
|
following configuration option:
|
|
|
|
```yaml
|
|
kramdown:
|
|
syntax_highlighter_opts:
|
|
block:
|
|
line_numbers: false
|
|
```
|
|
|
|
Line numbers can then be suppressed locally using Liquid tags (_without_ the
|
|
`linenos` option) instead of fences:
|
|
|
|
```
|
|
{% raw %}{% highlight some_language %}
|
|
Some code
|
|
{% endhighlight %}{% endraw %}
|
|
```
|
|
|
|
# Workarounds
|
|
|
|
To use HTML compression together with line numbers, all highlighted code
|
|
needs to be wrapped using one of the following workarounds.
|
|
(The variable name `some_var` can be changed to avoid clashes; it can also
|
|
be replaced by `code` -- but note that `code=code` cannot be removed).
|
|
|
|
## Code fences
|
|
|
|
````
|
|
{% raw %}{% capture some_var %}
|
|
```some_language
|
|
Some code
|
|
```
|
|
{% endcapture %}
|
|
{% assign some_var = some_var | markdownify %}
|
|
{% include fix_linenos.html code=some_var %}{% endraw %}
|
|
````
|
|
|
|
## Liquid highlighting
|
|
|
|
```
|
|
{% raw %}{% capture some_var %}
|
|
{% highlight some_language linenos %}
|
|
Some code
|
|
{% endhighlight %}
|
|
{% endcapture %}
|
|
{% include fix_linenos.html code=some_var %}{% endraw %}
|
|
```
|
|
|
|
_Credit:_ The original version of the above workaround was suggested by
|
|
Dmitry Hrabrov at
|
|
<https://github.com/penibelst/jekyll-compress-html/issues/71#issuecomment-188144901>.
|
|
|
|
# Examples
|
|
|
|
```
|
|
Some unknown code in fences
|
|
```
|
|
|
|
```js
|
|
// Javascript code with syntax highlighting in fences
|
|
var fun = function lang(l) {
|
|
dateformat.i18n = require('./lang/' + l)
|
|
return true;
|
|
}
|
|
```
|
|
|
|
```ruby
|
|
# Ruby code with syntax highlighting in fences
|
|
GitHubPages::Dependencies.gems.each do |gem, version|
|
|
s.add_dependency(gem, "= #{version}")
|
|
end
|
|
```
|
|
|
|
{% highlight ruby %}
|
|
# Ruby code with syntax highlighting using Liquid
|
|
GitHubPages::Dependencies.gems.each do |gem, version|
|
|
s.add_dependency(gem, "= #{version}")
|
|
end
|
|
{% endhighlight %}
|
|
|
|
{% capture code %}
|
|
{% highlight ruby linenos %}
|
|
# Ruby code with syntax highlighting and fixed line numbers using Liquid
|
|
GitHubPages::Dependencies.gems.each do |gem, version|
|
|
s.add_dependency(gem, "= #{version}")
|
|
end
|
|
{% endhighlight %}
|
|
{% endcapture %}
|
|
{% include fix_linenos.html code=code %}
|
|
{% assign code = nil %}
|
|
|
|
With the default configuration options, the following example illustrates
|
|
the incorrect formatting arising from the incompatibility of HTML compression
|
|
and the non-conforming HTML produced by Jekyll for line numbers:
|
|
|
|
{% highlight ruby linenos %}
|
|
# Ruby code with syntax highlighting and unfixed line numbers using Liquid
|
|
GitHubPages::Dependencies.gems.each do |gem, version|
|
|
s.add_dependency(gem, "= #{version}")
|
|
end
|
|
{% endhighlight %}
|