steve/just-the-docs
1
0
Fork 0
mirror of https://github.com/snachodog/just-the-docs.git synced 2025-04-25 04:22:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

docs: fix misleading docs on code with line numbers (#1349)

Browse Source 
Closes #1306.

Co-authored-by: Peter Mosses <18308236+pdmosses@users.noreply.github.com>
This commit is contained in:
Matt Wang 2023-11-15 11:45:14 -08:00 committed by GitHub
parent 4e7f8345b4
commit fd689b47e0
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 77 additions and 93 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
_includes/fix_linenos.html
View File

@ -1,29 +1,37 @@
{%- comment -%}
This file can be used to fix the HTML produced by Jekyll for highlighted
code with line numbers.
This file was previously used to "fix" the HTML produced by Jekyll for
highlighted code with line numbers. While it often resolves layout issues
from the missing HTML tags, it still generates invalid HTML (by placing
a `<table>` element within a `<code>` block). As such, we no longer
recommend using this workaround. For more information, see the
"Code snippets with line numbers" docs page:
https://just-the-docs.com/docs/ui-components/code/line-numbers/
(or, docs/ui-components/line-nos.md/)
It works with `{% highlight some_language linenos %}...{% endhighlight %}`
and with the Kramdown option to add line numbers to fenced code.
The next portion of this file, including the comments and the workaround,
are preserved for backwards comptability.
The implementation was derived from the workaround provided by
ACKNOWLEDGEMENTS
The implementation was derived from the workaround provided by
Dmitry Hrabrov (DeXP) at
https://github.com/penibelst/jekyll-compress-html/issues/71#issuecomment-188144901
EXPLANATION
EXPLANATION (OLD)
The HTML produced by Rouge highlighting with lie numbers is of the form
`code table`. Jekyll (<= 4.1.1) always wraps the highlighted HTML
The HTML produced by Rouge highlighting with line numbers is of the form
`code table`. Jekyll always wraps the highlighted HTML
with `pre`. This wrapping is not only unnecessary, but also transforms
the conforming HTML produced by Rouge to non-conforming HTML, which
results in HTML validation error reports.
results in HTML validation error reports.
The fix removes the outer `pre` tags whenever they contain the pattern
`<table class="rouge-table">`.
Apart from avoiding HTML validation errors, the fix allows the use of
the [Jekyll layout for compressing HTML](http://jch.penibelst.de),
which relies on `pre` tags not being nested, according to
https://github.com/penibelst/jekyll-compress-html/issues/71#issuecomment-172069842
https://github.com/penibelst/jekyll-compress-html/issues/71#issuecomment-172069842
USAGE
@ -48,7 +56,7 @@ Some code
CAVEATS
The above does not work when `Some code` happens to contain the matched string
The above does not work when `Some code` happens to contain the matched string
`<table class="rouge-table">`.
The use of this file overwrites the variable `fix_linenos_code` with `nil`.

2
docs/ui-components/code.md
View File

@ -58,6 +58,8 @@ var fun = function lang(l) {
```
{% endhighlight %}
Syntax highlighting, line numbers, and HTML compression do not work together; **the combination of these features generates invalid HTML that renders incorrectly**. To learn more, see ["Code with line numbers"]({% link docs/ui-components/line-nos.md %}).
---
## Code blocks with rendered examples

134
docs/ui-components/line-nos.md
View File

@ -8,8 +8,12 @@ permalink: /docs/ui-components/code/line-numbers/
# Code snippets with line numbers
{: .warning }
In prior versions of the docs, we provided "workarounds" to rendering issues arising from code snippets with line numbers. While these seemed to resolve visual layout issues, they did not resolve core issues with Jekyll generating invalid HTML. See [the detailed explanation](#detailed-error-explanation) for more information.
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
produced by Jekyll 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
@ -40,90 +44,62 @@ Some code
{% endhighlight %}{% endraw %}
{% endhighlight %}
## Workarounds
## Detailed Error Explanation
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).
Consider this following code snippet, intended to highlight a simple Ruby program:
### Code fences (three backticks)
{% highlight default %}
{% raw %}{% capture some_var %}
```some_language
Some code
```
{% endcapture %}
{% assign some_var = some_var | markdownify %}
{% include fix_linenos.html code=some_var %}{% endraw %}
{% endhighlight %}
### Liquid highlighting
{% highlight default %}
{% raw %}{% capture some_var %}
{% highlight some_language linenos %}
Some code
{% endhighlight %}
{% endcapture %}
{% include fix_linenos.html code=some_var %}{% endraw %}
{% endhighlight %}
_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
✅ Using code fences + workaround (will only show line numbers if enabled globally in `_config.yml`):
{% capture code_fence %}
```js
// Javascript code with syntax highlighting in fences
var fun = function lang(l) {
dateformat.i18n = require('./lang/' + l)
return true;
}
```
{% endcapture %}
{% assign code_fence = code_fence | markdownify %}
{% include fix_linenos.html code=code_fence %}
✅ Using liquid highlighting + workaround:
{% 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 %}
Narrow code stays close to the line numbers:
{% capture code %}
{% highlight ruby linenos %}
{% raw %}{% highlight ruby linenos %}
def foo
puts 'foo'
end
{% endhighlight %}
{% endcapture %}
{% include fix_linenos.html code=code %}
{% assign code = nil %}
{% endhighlight %}{% endraw %}
```
{: .warning }
The following generates **incorrect** and **invalid** HTML. It should not be used as a positive example; the improper layout (with the broken HTML tags) is intentional.
If this is directly placed within a file processed by Jekyll (via Just the Docs, with HTML compression enabled), the following markup will be generated:
❌ 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:
```html
<figure class="highlight">><code class="language-ruby" data-lang="ruby"><div class="table-wrapper"><table class="rouge-table"><tbody><tr><td class="gutter gl"><pre class="lineno">1
2
3
</pre><td class="code"><pre><span class="k">def</span> <span class="nf">foo</span>
<span class="nb">puts</span> <span class="s1">'foo'</span>
<span class="k">end</span>
</pre></figure>
```
{% highlight ruby linenos %}
def foo
puts 'foo'
end
{% endhighlight %}
This HTML is invalid; in particular, there are two issues:
1. there are many missing closing tags, and a superfluous `>`, which produce visually garbled output
2. a `<table>` is placed within a `<code>` element, which is syntactically invalid HTML (but is often allowed by browsers)
To emphasize this first difference, here is the same markup output, indented by tag:
```html
<figure class="highlight">
>
<code class="language-ruby" data-lang="ruby">
<div class="table-wrapper">
<table class="rouge-table">
<tbody>
<tr>
<td class="gutter gl">
<pre class="lineno">
1
2
3
</pre>
<td class="code">
<pre>
<span class="k">def</span>
<span class="nf">foo</span>
<span class="nb">puts</span>
<span class="s1">'foo'</span>
<span class="k">end</span>
</pre>
</figure>
```
In order, there are missing `</td>`, `</td>`, `</tr>`, `</tbody>`, `</table>`, `</div>`, and `</code>` tags. As a result, the following elements of the page - including the site footer - become visually garbled as browsers attempt to recover gracefully.
Prior workarounds we suggested (such as [Dmitry Hrabrov's in `jekyll-compress-html`#71](https://github.com/penibelst/jekyll-compress-html/issues/71#issuecomment-188144901)) resolve the missing tag problem. However, they still place a `<table>` within a `<code>` element. The HTML spec normatively states that `<code>` elements should only contain "[phrasing content](https://html.spec.whatwg.org/multipage/dom.html#phrasing-content-2)", which does not include `<table>` ([spec ref](https://html.spec.whatwg.org/multipage/text-level-semantics.html#the-code-element)). To avoid incorrectly rendered HTML, the previously-suggested workaround using the current version of `_includes/fix_linenos.html` should _not_ be used!

2
fixtures/html5validator-config.yml
View File

@ -1,3 +1 @@
root: _site
blacklist:
- "line-numbers"