steve/just-the-docs
1
0
Fork 0
mirror of https://github.com/snachodog/just-the-docs.git synced 2025-09-12 21:03:32 -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
4 changed files with 77 additions and 93 deletions
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`.