Better line numbers for Pygments HTML
=====================================
This library provides improved line numbers for the Pygments HTML formatter. The `BetterHtmlFormatter` supports two styles:
* `linenos="table"` (the default) — every line of the code is a separate table row (a 2xN table, as opposed to Pygments’ standard 2x1 table) This improves the appearance if the code contains characters with unusual line-height, and allows for the code to be word-wrapped with the numbers kept in the right places.
* `linenos="ol"` — lines are `<li>` elements in an `<ol>` list.
Both styles allow for copy-pasting into a code editor. Directly copy-pasting into Microsoft Word (or similar) might produce something ugly. The first style is inspired by GitHub, and the second can be seen at pastebin.com.
The `table` style is more flexible and looks better. The `ol` style is slightly more compatible with broken browsers and minifiers. Pick whichever one works best for you.
Usage
=====
In most cases, it’s a drop-in replacement for `HtmlFormatter`. Just add the import:
from pygments_better_html import BetterHtmlFormatter
and when calling `highlight()`, instead of `HtmlFormatter`, pass the `BetterHtmlFormatter` class:
BetterHtmlFormatter(linenos="table", …other options…)
BetterHtmlFormatter(linenos="ol", …other options…)
You can see a simple demo in `demo.py`.
Required CSS
------------
To make this work, you will need to add the following CSS:
```css
.highlight table, .highlight tr, .highlight td { border-spacing: 0; border-collapse: separate; padding: 0 }
.highlight pre { white-space: pre-wrap; line-height: normal }
.highlighttable td.linenos { vertical-align: top; padding-left: 10px; padding-right: 10px; user-select: none; -webkit-user-select: none }
.highlighttable td.linenos code:before { content: attr(data-line-number) }
.highlighttable td.code { overflow-wrap: normal; border-collapse: collapse }
.highlighttable td.code code { overflow: unset; border: none; padding: 0; margin: 0; white-space: pre-wrap; line-height: unset; background: none }
.highlight .lineno.nonumber { list-style: none }
```
If you’re using ``get_style_defs``, those will be included for you.
Browser support
===============
All reasonably modern versions of reasonable browsers are supported. Internet Explorer is neither, so it isn’t supported. Firefox, Chrome and Safari are supported. Either mode works with these browsers, although I’ve seen Firefox add extra spaces to the front of lines randomly, and Safari requires an ugly hack for the table mode.
Known limitations
=================
1. The `anchorlinenos` option is not supported for `linenos="ol"`.
2. Third-party minifier tools may destroy your indentation if you use tabs. Spaces use a work-around, described in the following point.
3. Because of overly clever HTML minifiers, ` ` tags are used for indentation and sequences of whitespace longer than one character. This might break in the event web browsers decide to copy non-breaking spaces as non-breaking instead of regular spaces. Currently, browsers do the right thing on all platforms. It might also lead to degraded apperance in some edge cases (indentation longer than the code box width, or long runs of spaces inside the code).
4. Some completely broken HTML minifiers will remove line numbers, because they are empty tags (that’s the only way to make Safari ignore them on copy-paste). Removing empty tags is just wrong, considering how many browser hacks were built on top of these throughout the years. I saw this issue with HTML Tidy, which is an antique tool detached from reality (even in the HTML5 fork).
If you care about compatiblity with bad tools or unusual scenarios, and don’t mind losing `anchorlinenos`, consider using the `lineos="ol"` mode instead of `lineos="table"`.
Browsers vs code vs minifiers
-----------------------------
Limitations (3) and (4) might be considered bugs in my code and not the minifiers. But note that browsers don’t ignore whitespace when parsing, and although the default `white-space: normal` setting for most tags collapses them, you can use `white-space: pre` or `white-space: pre-wrap` to display them. Those minifiers don’t take the CSS into account, and assume the default behavior, collapsing spaces outside of `<pre>` tags. Which is wrong if you override `white-space` on other elements, and “wasteful” if you do `pre { white-space: normal }` for some unusual reason (yeah, don’t do that.)
Collapsing whitespace could be worked around with a `<pre>` tag around each line of code, but Firefox will add extra newlines when copying (so the actual code is on every other line of the copied text). This is not avoidable and hard-coded (the plaintext conversion does not look at CSS either, and has a special case for `<pre>` since it makes sense for normal use of that tag. And you can’t wrap the entire table in a `<pre>` tag. If I added one, browsers would move it outside of the table to make the HTML valid. But if browsers do that, some of those clever minifiers might fix HTML syntax as well.
I decided to use a different solution, and work around these tools, by using non-breaking spaces for longer runs of spaces. This depends on web browsers replacing those with regular spaces when copying. Luckily, all browsers do this, and considering a 2008 4chan meme (“can’t triforce”, search results might be NSFW), that’s been a thing since forever and is not likely to change.
The selected solution of replacing runs of spaces with non-breaking spaces can lead to the code overflowing the box/adding a horizontal scrollbar. Those will happen only in very specific edge cases, i.e. very narrow windows + very large fonts + large indents + no regular (single) spaces close to the indent.
I also decided not to apply it to tabs (\t, ^I, U+0009 HORIZONTAL TAB), because tab width can be random, and tabs move the caret to a place, not by a set amount (so in `"a\tb"` and `"aa\tb"`, the `"b"` appears in the same place on the line). Which is generally difficult to handle properly, and you should be using spaces to indent your code anyway.
You should also note that GitHub uses both of these techniques, and BitBucket uses the first one. And that it’s easier for everyone to find a better tool if their current tool does stupid stuff.
License
=======
Copyright © 2020-2023, Chris Warrick. Licensed under the 3-clause BSD license.
Many parts of the code are taken from Pygments’ original HTMLFormatter, which is copyright © 2006-2022 by the Pygments team, and is licensed under the 2-clause BSD license.
Raw data
{
"_id": null,
"home_page": "https://github.com/Kwpolska/pygments_better_html",
"name": "pygments-better-html",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "pygments,html,code,highlighting",
"author": "Chris Warrick",
"author_email": "chris@chriswarrick.com",
"download_url": "https://files.pythonhosted.org/packages/d3/b2/87ce67d509d75766f3392fc9d5712e533452f48e24f583e856bba7938495/pygments_better_html-0.1.5.tar.gz",
"platform": "any",
"description": "Better line numbers for Pygments HTML\n=====================================\n\nThis library provides improved line numbers for the Pygments HTML formatter. The `BetterHtmlFormatter` supports two styles:\n\n* `linenos=\"table\"` (the default) \u2014 every line of the code is a separate table row (a 2xN table, as opposed to Pygments\u2019 standard 2x1 table) This improves the appearance if the code contains characters with unusual line-height, and allows for the code to be word-wrapped with the numbers kept in the right places.\n* `linenos=\"ol\"` \u2014 lines are `<li>` elements in an `<ol>` list.\n\nBoth styles allow for copy-pasting into a code editor. Directly copy-pasting into Microsoft Word (or similar) might produce something ugly. The first style is inspired by GitHub, and the second can be seen at pastebin.com.\n\nThe `table` style is more flexible and looks better. The `ol` style is slightly more compatible with broken browsers and minifiers. Pick whichever one works best for you.\n\nUsage\n=====\n\nIn most cases, it\u2019s a drop-in replacement for `HtmlFormatter`. Just add the import:\n\n from pygments_better_html import BetterHtmlFormatter\n\nand when calling `highlight()`, instead of `HtmlFormatter`, pass the `BetterHtmlFormatter` class:\n\n BetterHtmlFormatter(linenos=\"table\", \u2026other options\u2026)\n BetterHtmlFormatter(linenos=\"ol\", \u2026other options\u2026)\n\nYou can see a simple demo in `demo.py`.\n\nRequired CSS\n------------\n\nTo make this work, you will need to add the following CSS:\n\n```css\n.highlight table, .highlight tr, .highlight td { border-spacing: 0; border-collapse: separate; padding: 0 }\n.highlight pre { white-space: pre-wrap; line-height: normal }\n.highlighttable td.linenos { vertical-align: top; padding-left: 10px; padding-right: 10px; user-select: none; -webkit-user-select: none }\n.highlighttable td.linenos code:before { content: attr(data-line-number) }\n.highlighttable td.code { overflow-wrap: normal; border-collapse: collapse }\n.highlighttable td.code code { overflow: unset; border: none; padding: 0; margin: 0; white-space: pre-wrap; line-height: unset; background: none }\n.highlight .lineno.nonumber { list-style: none }\n```\n\nIf you\u2019re using ``get_style_defs``, those will be included for you.\n\nBrowser support\n===============\n\nAll reasonably modern versions of reasonable browsers are supported. Internet Explorer is neither, so it isn\u2019t supported. Firefox, Chrome and Safari are supported. Either mode works with these browsers, although I\u2019ve seen Firefox add extra spaces to the front of lines randomly, and Safari requires an ugly hack for the table mode.\n\nKnown limitations\n=================\n\n1. The `anchorlinenos` option is not supported for `linenos=\"ol\"`.\n2. Third-party minifier tools may destroy your indentation if you use tabs. Spaces use a work-around, described in the following point.\n3. Because of overly clever HTML minifiers, ` ` tags are used for indentation and sequences of whitespace longer than one character. This might break in the event web browsers decide to copy non-breaking spaces as non-breaking instead of regular spaces. Currently, browsers do the right thing on all platforms. It might also lead to degraded apperance in some edge cases (indentation longer than the code box width, or long runs of spaces inside the code).\n4. Some completely broken HTML minifiers will remove line numbers, because they are empty tags (that\u2019s the only way to make Safari ignore them on copy-paste). Removing empty tags is just wrong, considering how many browser hacks were built on top of these throughout the years. I saw this issue with HTML Tidy, which is an antique tool detached from reality (even in the HTML5 fork).\n\nIf you care about compatiblity with bad tools or unusual scenarios, and don\u2019t mind losing `anchorlinenos`, consider using the `lineos=\"ol\"` mode instead of `lineos=\"table\"`.\n\nBrowsers vs code vs minifiers\n-----------------------------\n\nLimitations (3) and (4) might be considered bugs in my code and not the minifiers. But note that browsers don\u2019t ignore whitespace when parsing, and although the default `white-space: normal` setting for most tags collapses them, you can use `white-space: pre` or `white-space: pre-wrap` to display them. Those minifiers don\u2019t take the CSS into account, and assume the default behavior, collapsing spaces outside of `<pre>` tags. Which is wrong if you override `white-space` on other elements, and \u201cwasteful\u201d if you do `pre { white-space: normal }` for some unusual reason (yeah, don\u2019t do that.)\n\nCollapsing whitespace could be worked around with a `<pre>` tag around each line of code, but Firefox will add extra newlines when copying (so the actual code is on every other line of the copied text). This is not avoidable and hard-coded (the plaintext conversion does not look at CSS either, and has a special case for `<pre>` since it makes sense for normal use of that tag. And you can\u2019t wrap the entire table in a `<pre>` tag. If I added one, browsers would move it outside of the table to make the HTML valid. But if browsers do that, some of those clever minifiers might fix HTML syntax as well.\n\nI decided to use a different solution, and work around these tools, by using non-breaking spaces for longer runs of spaces. This depends on web browsers replacing those with regular spaces when copying. Luckily, all browsers do this, and considering a 2008 4chan meme (\u201ccan\u2019t triforce\u201d, search results might be NSFW), that\u2019s been a thing since forever and is not likely to change.\n\nThe selected solution of replacing runs of spaces with non-breaking spaces can lead to the code overflowing the box/adding a horizontal scrollbar. Those will happen only in very specific edge cases, i.e. very narrow windows + very large fonts + large indents + no regular (single) spaces close to the indent.\n\nI also decided not to apply it to tabs (\\t, ^I, U+0009 HORIZONTAL TAB), because tab width can be random, and tabs move the caret to a place, not by a set amount (so in `\"a\\tb\"` and `\"aa\\tb\"`, the `\"b\"` appears in the same place on the line). Which is generally difficult to handle properly, and you should be using spaces to indent your code anyway.\n\nYou should also note that GitHub uses both of these techniques, and BitBucket uses the first one. And that it\u2019s easier for everyone to find a better tool if their current tool does stupid stuff.\n\nLicense\n=======\n\nCopyright \u00a9 2020-2023, Chris Warrick. Licensed under the 3-clause BSD license.\n\nMany parts of the code are taken from Pygments\u2019 original HTMLFormatter, which is copyright \u00a9 2006-2022 by the Pygments team, and is licensed under the 2-clause BSD license.\n",
"bugtrack_url": null,
"license": "3-clause BSD",
"summary": "Better HTML formatter for Pygments",
"version": "0.1.5",
"project_urls": {
"Homepage": "https://github.com/Kwpolska/pygments_better_html"
},
"split_keywords": [
"pygments",
"html",
"code",
"highlighting"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e84d14c5c6c8fe74e9e4e6500de8be70777e5d98d86796baae850e789169af14",
"md5": "ed47f90d61a21b7328289f6eb560d142",
"sha256": "56b29d997c87d1a4bcf030b275776ece3248fb7139d209dd4f4c00d62d5f0d62"
},
"downloads": -1,
"filename": "pygments_better_html-0.1.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ed47f90d61a21b7328289f6eb560d142",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 9310,
"upload_time": "2023-07-25T21:26:24",
"upload_time_iso_8601": "2023-07-25T21:26:24.899012Z",
"url": "https://files.pythonhosted.org/packages/e8/4d/14c5c6c8fe74e9e4e6500de8be70777e5d98d86796baae850e789169af14/pygments_better_html-0.1.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d3b287ce67d509d75766f3392fc9d5712e533452f48e24f583e856bba7938495",
"md5": "744179188613e627dba10b75b2b904d8",
"sha256": "48b01ee6e6c818472150da0709cb7a0968ac0636b758d11fa44e3cbfd093ccf4"
},
"downloads": -1,
"filename": "pygments_better_html-0.1.5.tar.gz",
"has_sig": false,
"md5_digest": "744179188613e627dba10b75b2b904d8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 9839,
"upload_time": "2023-07-25T21:26:26",
"upload_time_iso_8601": "2023-07-25T21:26:26.689933Z",
"url": "https://files.pythonhosted.org/packages/d3/b2/87ce67d509d75766f3392fc9d5712e533452f48e24f583e856bba7938495/pygments_better_html-0.1.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-25 21:26:26",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Kwpolska",
"github_project": "pygments_better_html",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "pygments-better-html"
}
JSON
