From 61053f677b7e9808fb14ee851d28a89361980f55 Mon Sep 17 00:00:00 2001 From: PLanCompS <18308236+pdmosses@users.noreply.github.com> Date: Tue, 7 Jul 2020 19:34:35 +0200 Subject: [PATCH] Major refactoring 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). --- _config.yml | 7 +++ _sass/code.scss | 100 ++++++++++++++++--------------------------- docs/linenos-test.md | 75 ++++++++++++++++++++++++++++++-- 3 files changed, 115 insertions(+), 67 deletions(-) diff --git a/_config.yml b/_config.yml index 20bf8a1..aca049e 100644 --- a/_config.yml +++ b/_config.yml @@ -99,6 +99,11 @@ ga_tracking_anonymize_ip: true # Use GDPR compliant Google Analytics settings (t plugins: - jekyll-seo-tag +kramdown: + syntax_highlighter_opts: + block: + line_numbers: false + compress_html: clippings: all comments: all @@ -106,3 +111,5 @@ compress_html: startings: [] blanklines: false profile: false + # ignore: + # envs: all diff --git a/_sass/code.scss b/_sass/code.scss index 864c9b0..4836a1e 100644 --- a/_sass/code.scss +++ b/_sass/code.scss @@ -38,55 +38,58 @@ code { // No kramdown line_numbers: fences and Liquid highlighting look the same. // Kramdown line_numbers = true: fences have a wider gutter than with Liquid? -pre.highlight, -figure.highlight { +// ```[LANG]...``` +div.highlighter-rouge { padding: $sp-3; margin-top: 0; - margin-bottom: 0; - background-color: $code-background-color; - border-radius: $border-radius; - -webkit-overflow-scrolling: touch; - - code { - padding: 0; - border: 0; - } -} - -// Using Liquid tags for highlighting, optionally with linenos - -// Without linenos: figure.highlight > pre > code > div > span* - -figure.highlight, -div.highlight { - padding: 0; - margin-top: 0; margin-bottom: $sp-3; background-color: $code-background-color; border-radius: $border-radius; + box-shadow: none; -webkit-overflow-scrolling: touch; - pre { - padding: $sp-3; - margin-top: 0; - margin-bottom: 0; + div.highlight, + pre.highlight, + code { + padding: 0; + margin: 0; + border: 0; } } -// With linenos or kramdown line_numbers option: +// {% highlight LANG [linenos] %}...{% endhighlight %}: +figure.highlight { + padding: $sp-3; + margin-top: 0; + margin-bottom: $sp-3; + background-color: $code-background-color; + border-radius: $border-radius; + box-shadow: none; + -webkit-overflow-scrolling: touch; -figure.highlight > pre > code, -figure.highlight > code, -div.highlight > pre > code, -div.highlight > code { - td, + pre, + code { + padding: 0; + margin: 0; + border: 0; + } +} + +// ```[LANG]...```, kramdown line_numbers = true, +// {% highlight LANG linenos %}...{% endhighlight %}: +.highlight .table-wrapper { + padding: 0; + margin: 0; + border: 0; + box-shadow: none; + + tr > td, td > pre { @include fs-2; min-width: 0; padding: 0; + border: 0; background-color: $code-background-color; - border-bottom: 0; - border-left: 0; } td.gl { @@ -94,38 +97,9 @@ div.highlight > code { } pre { - margin-top: 0; + margin: 0; line-height: 2; } - - tbody > tr > td { - padding-bottom: 0; - border-bottom: 0; - } -} - -// Jekyll 4.1.1: figure.highlight > pre > code > div > table > ... - -figure.highlight > pre > code .table-wrapper, -div.highlight > pre > code .table-wrapper { - padding: 0; - margin-bottom: 0; - border: 0; - box-shadow: none; -} - -// Using fix_linenos: figure.highlight > code > div > table > ... - -figure.highlight > code .table-wrapper, -div.highlight > code .table-wrapper { - padding: $sp-3; - margin-bottom: 0; - border: 0; - box-shadow: none; -} - -.highlighter-rouge { - margin-bottom: $sp-3; } .highlight .c { diff --git a/docs/linenos-test.md b/docs/linenos-test.md index 48e9603..8d6962e 100644 --- a/docs/linenos-test.md +++ b/docs/linenos-test.md @@ -4,17 +4,80 @@ title: Markdown line number test nav_order: 999 --- -``` -Some unknown code in fences -``` +# 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: -Some of the code examples below require the following setting in `_config.yml`: ```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 +. + +# Examples + +``` +Some unknown code in fences +``` + ```js // Javascript code with syntax highlighting in fences var fun = function lang(l) { @@ -48,6 +111,10 @@ end {% 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|