From 93857587dd42bb397be4cb49eb51fcae4f416f2a Mon Sep 17 00:00:00 2001
From: Peter Mosses <18308236+pdmosses@users.noreply.github.com>
Date: Tue, 27 Sep 2022 18:53:57 +0200
Subject: [PATCH] Improve docs for code highlighting with line numbers (#974)

* Add toc heading custom include

Closes #961.

* Revert "Add toc heading custom include"

This reverts commit 49813c341973e313db0a21f075a60ebf2120989e.

* Update code highlighting with line numbers

- Add the example of code highlighting with line numbers explained in the [Jekyll docs](https://jekyllrb.com/docs/liquid/tags/#line-numbers).
- Fix the styling of narrow code with line numbers, which floats to the centre without this CSS adjustment. (The line numbers column expands as needed with larger numbers of lines, despite using `width`; using `min-width` doesn't work.)

To apply HTML compression, I removed `vendor` from `exclude`; that change is left to a different PR.
---
 _sass/code.scss                |  1 +
 docs/ui-components/line-nos.md | 19 +++++++++++++++----
 2 files changed, 16 insertions(+), 4 deletions(-)

diff --git a/_sass/code.scss b/_sass/code.scss
index 384ef97f..1ac7adc7 100644
--- a/_sass/code.scss
+++ b/_sass/code.scss
@@ -106,6 +106,7 @@ figure.highlight {
   }
 
   td.gl {
+    width: 1em;
     padding-right: $sp-3;
   }
 
diff --git a/docs/ui-components/line-nos.md b/docs/ui-components/line-nos.md
index 1baa3da9..62870c12 100644
--- a/docs/ui-components/line-nos.md
+++ b/docs/ui-components/line-nos.md
@@ -103,13 +103,24 @@ end
 {% include fix_linenos.html code=code %}
 {% assign code = nil %}
 
-❌ With the default configuration options, the following example illustrates
+Narrow code stays close to the line numbers:
+
+{% capture code %}
+{% highlight ruby linenos %}
+def foo
+  puts 'foo'
+end
+{% endhighlight %}
+{% endcapture %}
+{% include fix_linenos.html code=code %}
+{% assign code = nil %}
+
+❌ With the compression options used for the theme docs, 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}")
+def foo
+  puts 'foo'
 end
 {% endhighlight %}
-- 
GitLab