{"id":14885529,"url":"https://github.com/lyokha/vim-publish-helper","last_synced_at":"2025-10-29T08:33:55.223Z","repository":{"id":12913693,"uuid":"15591088","full_name":"lyokha/vim-publish-helper","owner":"lyokha","description":"vim plugin that makes vim syntax highlighting engine available in pandoc","archived":false,"fork":false,"pushed_at":"2024-10-23T15:38:14.000Z","size":624,"stargazers_count":15,"open_issues_count":0,"forks_count":0,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-10-23T20:51:58.335Z","etag":null,"topics":["filter","highlighting","neovim","pandoc","tree-sitter","vim"],"latest_commit_sha":null,"homepage":"","language":"Vim Script","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lyokha.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-01-02T18:56:17.000Z","updated_at":"2024-10-23T15:38:19.000Z","dependencies_parsed_at":"2023-12-21T15:40:10.734Z","dependency_job_id":"ad7dbdf7-fcce-4862-950b-d1d75faf72f5","html_url":"https://github.com/lyokha/vim-publish-helper","commit_stats":{"total_commits":254,"total_committers":1,"mean_commits":254.0,"dds":0.0,"last_synced_commit":"bff2f88460c0c960f117b6b882fd7730e4bae998"},"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lyokha%2Fvim-publish-helper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lyokha%2Fvim-publish-helper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lyokha%2Fvim-publish-helper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lyokha%2Fvim-publish-helper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lyokha","download_url":"https://codeload.github.com/lyokha/vim-publish-helper/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238795472,"owners_count":19531752,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["filter","highlighting","neovim","pandoc","tree-sitter","vim"],"created_at":"2024-09-21T16:01:25.313Z","updated_at":"2025-10-29T08:33:54.812Z","avatar_url":"https://github.com/lyokha.png","language":"Vim Script","funding_links":[],"categories":["Vim Script"],"sub_categories":[],"readme":"Vim-publish-helper\n==================\n\n[![Build Status](https://github.com/lyokha/vim-publish-helper/workflows/vimhl/badge.svg)](https://github.com/lyokha/vim-publish-helper/actions?query=workflow%3Avimhl)\n[![Hackage](https://img.shields.io/hackage/v/pandoc-vimhl.svg?label=hackage%20%7C%20pandoc-vimhl\u0026logo=haskell\u0026logoColor=%239580D1)](https://hackage.haskell.org/package/pandoc-vimhl)\n\nTable of contents\n-----------------\n\n- [About](#about)\n- [Basic commands](#basic-commands)\n    + [MakeHtmlCodeHighlight](#makehtmlcodehighlight)\n    + [MakeTexCodeHighlight](#maketexcodehighlight)\n- [vimhl.hs and pandoc](#vimhlhs-and-pandoc)\n    + [Basic usage](#basic-usage)\n    + [Using with dedicated .vimrc file](#using-with-dedicated-.vimrc-file)\n    + [Customizing vim settings](#customizing-vim-settings)\n    + [Options to choose color scheme](#options-to-choose-color-scheme)\n    + [Remarks](#remarks)\n- [Miscellaneous commands](#miscellaneous-commands)\n    + [GetFgColorUnderCursor](#getfgcolorundercursor)\n    + [GetBgColorUnderCursor](#getbgcolorundercursor)\n- [Configuration](#configuration)\n    + [g:PhColorscheme](#gphcolorscheme)\n    + [g:PhHighlightEngine](#gphhighlightengine)\n    + [g:PhHtmlEngine](#gphhtmlengine)\n    + [g:PhHtmlPreAttrs](#gphhtmlpreattrs)\n    + [g:PhTexBlockStyle](#gphtexblockstyle)\n    + [g:PhCtrlTrans](#gphctrltrans)\n    + [g:PhTrimBlocks](#gphtrimblocks)\n    + [g:PhRichTextElems](#gphrichtextelems)\n    + [g:PhLinenrAsTblColumn](#gphlinenrastblcolumn)\n- [Highlighting shells and REPLs](#highlighting-shells-and-repls)\n- [An example](#an-example)\n- [Trivia](#trivia)\n- [Thanks to](#thanks-to)\n\nAbout\n-----\n\nVim plugin *publish\\_helper* provides two basic commands *MakeHtmlCodeHighlight*\nand *MakeTexCodeHighlight* to produce HTML or TeX code respectively from the\ncontents of the current buffer or a part of the current buffer (in Visual\nmode). The generated code opens up in a new window and contains color tags\nthat cite colors from the original buffer according to the current vim color\nscheme or a color scheme declared by variable *g:PhColorscheme*.\n\nThe distribution of the plugin is shipped with a haskell program *vimhl.hs*\ndesigned as a filter for a great text conversion tool\n[*pandoc*](http://pandoc.org/), which makes it possible to use vim internal\nsyntax highlighting engine when converting from various text formats (including\n*markdown*) into HTML or TeX.\n\nBasic commands\n--------------\n\n### MakeHtmlCodeHighlight\n\nProduces HTML code from the contents of the current buffer or a selected part\nof it. Uses plugin *TOhtml* internally with temporarily set variable\n*g:html\\_use\\_css = 0*, thus embedding color tags inside the generated HTML\ncode. Wraps the generated HTML code inside *\u0026lt;pre\u0026gt; ... \u0026lt;/pre\u0026gt;* tags.\nYou can copy it in a clipboard and then insert in any HTML document: an article\nin your blog, HTML book, etc. The code highlights will look the same as in your\nvim session!\n\nThe command may accept an optional argument that defines if the generated\ncode will be numbered in the resulting document and what number the first line\nwill be. If this argument is missing then line numbers will not be generated.\nOtherwise, if it is a positive integer then the number of the first line of the\ngenerated code will be equal to this value, if it is a negative integer then\nthe number of the first line will be equal to the number of the first line in\nthe original buffer.\n\nStarting from **version 0.6**, *MakeHtmlCodeHighlight* uses the same\nhighlighting engine as *MakeTexCodeHighlight* by default. To switch back to the\n*TOhtml* engine, set variable *g:PhHtmlEngine = 'tohtml'*.\n\nOutput of *TOhtml* may differ from that of the default highlighting engine: it\nrenders buffers in a very verbose way and may content folds, bold text etc.,\nwhereas default engine normally ignores view details of the buffer.\n\nNote that in *Neovim* *0.10* plugin *TOhtml* was rewritten in a non-compatible\nway and therefore the *TOhtml* engine was disabled in this version of *Neovim*.\n\n### MakeTexCodeHighlight\n\nBasically, this command is a twin of the previous one, only it produces a TeX\ncode that is compatible with TeX documents generated by pandoc. As such, the\ngenerated TeX code contains color tags corresponding to the vim color scheme\nused, and is wrapped inside tags\n\n```tex\n\\begin{Shaded}\n\\begin{Highlighting}[]\n```\n\nand\n\n```tex\n\\end{Highlighting}\n\\end{Shaded}\n```\n\nStarting from **version 0.9**, the environment name (*Shaded*) is no longer\nhard-coded but defined by variable *g:PhTexBlockStyle*. This allows applying\ndifferent styles for code blocks in TeX documents.\n\nvimhl.hs and pandoc\n-------------------\n\nThis is perhaps the most useful feature of the plugin. Both commands\n*MakeHtmlCodeHighlight* and *MakeTexCodeHighlight* can be used as drivers to the\nvim syntax highlighting engine from pandoc. This is achieved via the *filter*\nfeature available in pandoc since version *1.12*.\n\n### Basic usage\n\nThis distribution is shipped with a haskell program *vimhl.hs* which is supposed\nto be such a filter. Normally, one may want to compile it,\n\n```ShellSession\n$ ghc --make vimhl\n```\n\nand move the built binary executable file *vimhl* in some directory listed in\nthe environment variable *\u0026#36;PATH*. Alternatively, *vimhl* can be installed\nwith *cabal*.\n\n```ShellSession\n$ cabal install pandoc-vimhl\n```\n\nAfter that, pandoc gets capable to produce HTML or TeX code with authentic vim\nsyntax highlights! Let's make an example. Say, you want to convert an HTML\narticle from a blog with multiple examples of C++ code into PDF via the pandoc\nconversion tool. Normally, you open the article, find tags *\u0026lt;pre\u0026gt;* that\nstart C++ code, and add there attribute *class=\"cpp\"*.\n\n```html\n\u003cpre class=\"cpp\"\u003e\n```\n\nAfter that, you run pandoc to create TeX code from the original HTML article.\n\n```ShellSession\n$ pandoc -f html -t latex -o article.tex article.html\n```\n\nAs far as pandoc finds attribute *class=\"cpp\"* inside tags\n*\u0026lt;pre\u0026gt; ... \u0026lt;/pre\u0026gt;*, it generates its own code highlights based on\nthe editor *Kate*'s engine. Now you can add another attribute *hl=\"vim\"* inside\ntags *\u0026lt;pre\u0026gt;*,\n\n```html\n\u003cpre class=\"cpp\" hl=\"vim\"\u003e\n```\n\nand run pandoc with *vimhl* as a filter.\n\n```ShellSession\n$ pandoc -f html -t latex -F vimhl -o article.tex article.html\n```\n\nIf you then generate a PDF document from the *article.tex*, the C++ code will be\nhighlighted exactly as it was highlighted inside vim! As soon as command\n*MakeTexCodeHighlight* accepts the optional argument which defines that the\ngenerated code must be numbered, you can put usual pandoc options inside tags\n*\u0026lt;pre\u0026gt;* to turn code numbering on.\n\n```html\n\u003cpre class=\"cpp numberLines\" hl=\"vim\" startFrom=\"100\"\u003e\n```\n\nNotice that *vimhl* runs program named *vim*. You may also want to specify the\nflavor of vim or where to find it by setting environment variable\n*VIMHL_BACKEND*. Say,\n\n```ShellSession\n$ export VIMHL_BACKEND=nvim\n```\n\nor\n\n```ShellSession\n$ export VIMHL_BACKEND=/usr/local/bin/vim\n```\n\n### Using with dedicated .vimrc file\n\nRunning vim with normal *\u0026#36;HOME/.vimrc* and all the scripts in the directory\n*\u0026#36;HOME/.vim/* consumes many resources and unnecessarily slows pandoc down.\nTo fight this, you can create a new file *.vimrc.pandoc* in your home directory\nwith very minimal settings. When *vimhl.hs* finds this file, it runs vim with\noptions *--noplugin -u \u0026#36;HOME/.vimrc.pandoc*. As soon as plugins are turned\noff, *.vimrc.pandoc* must source at least plugins *publish\\_helper* and *TOhtml*\n(for producing HTML documents, but since **version 0.6** of the plugin this is\noptional). Here is an example of a good *.vimrc.pandoc* contents:\n\n```vim\nset nocompatible\n\nfiletype off    \" filetype is set by vimhl\n\nlet g:lucius_style = 'light'\nlet g:lucius_contrast = 'high'\nlet g:lucius_contrast_bg = 'high'\n\ncolorscheme lucius\nsyntax on\n\nlet g:PhCtrlTrans = 0\n\nruntime plugin/publish_helper.vim\n\n\" vim: ft=vim\n```\n\nYou may need to source other plugins, for example *TagHighlight* which makes it\npossible to highlight tags generated by program *ctags*.\n\nStarting from **version 0.15**, the path to the custom *.vimrc* script can be\nset in environment variable *VIMRC_PANDOC*.\n\n### Customizing vim settings\n\nStarting from **version 0.7**, *vimhl* accepts a new attribute *vars* to define\nglobal vim variables. The example of a custom *.vimrc.pandoc* script from the\nprevious section contains definition of a global variable *g:PhCtrlTrans*. Now\nyou can remove this definition from the script and set variable *g:PhCtrlTrans*\ndynamically from the filter only for those code blocks that require it. To\naccomplish this, put attribute *vars=\"PhCtrlTrans\"* in such code blocks.\n\nGlobal variables are also good for making selection between arbitrary\nconditions. Imagine that script *.vimrc.pandoc* contains lines\n\n```vim\nif exists('g:load_TagHl')\n    colorscheme bandit\n    runtime plugin/TagHighlight.vim\n    let g:TagHighlightSettings['LanguageDetectionMethods'] = ['FileType']\nendif\n\nif exists('g:PhHtmlEngine') \u0026\u0026 g:PhHtmlEngine == 'tohtml'\n    runtime plugin/tohtml.vim\n    let g:html_no_progress = 1\n    let g:html_ignore_folding = 1\nendif\n```\n\nThe first condition says that if a global variable *g:load_TagHl* exists then\n*vimhl* must use color scheme *bandit* and load plugin *TagHighlight* that would\nnormally add extra highlighting groups to make code highlights look richer and\nmore beautiful. The second condition says that if a global variable\n*g:PhHtmlEngine* exists and is equal to *tohtml* then *vimhl* must load plugin\n*TOhtml*.\n\nAttribute *vars* allows for loading vim global variables from the original\ndocument. To turn conditions in the example above on, it must be defined as\n*vars=\"load_TagHl,PhHtmlEngine=tohtml\"*. This example shows that variables must\nbe delimited by *commas*, their values are defined after an *equal sign*, if the\nequal sign is missing then the value is supposed to be equal to *1*, *quote\nsigns* around the value and prefix *g:* before variable names are omitted and\nwill be substituted automatically inside *vimhl*.\n\n### Options to choose color scheme\n\nHere is the algorithm for choosing a color scheme in priority order:\n\n* If tag *\u0026lt;pre\u0026gt;* contains attribute *colorscheme=\"\u0026lt;value\u0026gt;\"* then\n  *\u0026lt;value\u0026gt;* is chosen, else\n\n* If file *\u0026#36;HOME/.vimrc.pandoc* contains line *colorscheme \u0026lt;value\u0026gt;*\n  then *\u0026lt;value\u0026gt;* is chosen, else\n\n* If file *\u0026#36;HOME/.vimrc* contains line\n  *let g:PhColorscheme = \"\u0026lt;value\u0026gt;\"* then *\u0026lt;value\u0026gt;* is chosen, else\n\n* If file *\u0026#36;HOME/.vimrc contains* line *colorscheme \u0026lt;value\u0026gt;* then\n  *\u0026lt;value\u0026gt;* is chosen, else\n\n* System vim color scheme is chosen\n\nThe second case, i.e. when *colorscheme* is defined in file\n*\u0026#36;HOME/.vimrc.pandoc*, is preferable because vim will consume less resources\nand work faster.\n\n### Remarks\n\n* Attribute *class* may contain a list of values. To make *vimhl.hs* work\n  properly, the filetype must be the first value in this list.\n\n* Normally, pandoc adds definitions of *Shaded* and *Highlighting* environments\n  in TeX output when it finds *CodeBlock* branches in the generated AST. The\n  *publish\\_helper* will replace *CodeBlock* branches with *RawBlock* branches,\n  and pandoc may skip inserting those definitions. In this case you can add them\n  manually in the preamble of the TeX document:\n\n    ```tex\n  \\usepackage{xcolor}\n  \\usepackage{fancyvrb}\n  \\newcommand{\\VerbBar}{|}\n  \\newcommand{\\VERB}{\\Verb[commandchars=\\\\\\{\\}]}\n  \\DefineVerbatimEnvironment{Highlighting}{Verbatim}{commandchars=\\\\\\{\\}}\n  \\usepackage{framed}\n  \\newenvironment{Shaded}{\n      \\definecolor{shadecolor}{rgb}{1.0, 1.0, 0.9}\n      \\setlength\\parskip{0cm}\n      \\setlength\\partopsep{-\\topsep}\n      \\addtolength\\partopsep{0.2cm}\n      \\begin{shaded}\n          \\scriptsize\n  }{\\end{shaded}}\n    ```\n\n  All settings inside environment *Shaded* are optional. For example, value of\n  *shadecolor* defines background color of the code block: if you do not want\n  that code blocks in your documents have specific background color then simply\n  do not define it in *Shaded* environment.\n\n  You may also want to use script *vimhl_latex_tmpl.sh* shipped with the plugin\n  in order to facilitate this task. The script prints to *stdout* a pandoc\n  template for Latex which is compatible with *vimhl*. Besides *Shaded*\n  environment, it defines *Snugshade*, *Framed*, *Leftbar*, and *Mdframed*\n  environments that correspond to definitions of the same names in Latex\n  packages *Framed* and *Mdframed*.\n\n  Normally, the output has to be redirected to a file in the standard pandoc\n  templates directory.\n\n    ```ShellSession\n  $ bash vimhl_latex_tmpl.sh \u003e ~/.pandoc/templates/vimhl.latex\n    ```\n\n  Now you can use this template for making standalone TeX or PDF documents\n  using pandoc's option *--template=vimhl*. The script accepts a number of\n  options to customize visual parameters of code blocks. To see them, use\n  option *-h*.\n\nMiscellaneous commands\n----------------------\n\nThere are two additional commands *GetFgColorUnderCursor* and\n*GetBgColorUnderCursor*. They have nothing to do with the code highlighting task\nand were added for debugging purposes only. You can map them like\n\n```vim\nnmap \u003csilent\u003e ,vf :GetFgColorUnderCursor\u003cCR\u003e\nnmap \u003csilent\u003e ,vb :GetBgColorUnderCursor\u003cCR\u003e\n```\n\nand find foreground or background colors under cursor with a simple keystroke.\n\n### GetFgColorUnderCursor\n\nGets foreground color under cursor.\n\n### GetBgColorUnderCursor\n\nGets background color under cursor.\n\nConfiguration\n-------------\n\n### g:PhColorscheme\n\n```vim\nlet g:PhColorscheme = 'lucius'\n```\n\nThis variable specifies dedicated color scheme for syntax highlights by\n*MakeHtmlCodeHighlight* and *MakeTexCodeHighlight*. If not set, then the current\ncolor scheme will be used. Do not set it in *.vimrc.pandoc* because normal\nsetting of a color scheme is preferred there.\n\n### g:PhHighlightEngine\n\n```vim\nlet g:PhHighlightEngine = 'treesitter'\n```\n\nAvailable since **version 0.13**. If value is *treesitter* then running commands\n*MakeHtmlCodeHighlight* and *MakeTexCodeHighlight* in *Neovim* with a\ntreesitter-aware color scheme will make use of highlighting groups built by\ntreesitter. Has no effect when rendering HTML if value of *g:PhHtmlEngine* is\n*tohtml*. Also affects the output of commands *GetFgColorUnderCursor* and\n*GetBgColorUnderCursor*.\n\n### g:PhHtmlEngine\n\n```vim\nlet g:PhHtmlEngine = 'tohtml'\n```\n\nAvailable since **version 0.6**. If value is *tohtml* then *TOhtml* engine will\nbe used to render HTML highlights, otherwise the internal engine will be used.\nNot set by default.\n\n### g:PhHtmlPreAttrs\n\nThis variable sets attributes that will be inserted inside tags *\u0026lt;pre\u0026gt;* in\ngenerated HTML documents. Examples:\n\n```vim\nlet g:PhHtmlPreAttrs = 'style=\"white-space: pre-wrap;\"'\n```\n\n```vim\nlet g:PhHtmlPreAttrs = 'style=\"overflow-x: auto;\"'\n```\n\n### g:PhTexBlockStyle\n\nThis variable sets visual parameters of code blocks in generated TeX documents.\nIf not set, then *Shaded* environment will be used. Examples:\n\n```vim\nlet g:PhTexBlockStyle = 'Shaded'\n```\n\n```vim\nlet g:PhTexBlockStyle = 'Framed'\n```\n\n### g:PhCtrlTrans\n\n```vim\nlet g:PhCtrlTrans = 1\n```\n\nSome programming languages allow using verbatim control characters. For\nexample, you may define an interactive scenario in *viml* with command *normal*\nwhich may require them. This variable specifies that *MakeTexCodeHighlight* will\naccurately translate verbatim control characters in their usual vim *ascii*\nrepresentation. Setting this variable for using from *vimhl.hs* does not always\nwork as expected because some values (like *^M*) may have been already lost on\nthe pandoc's AST level. This variable is not set by default.\n\n### g:PhTrimBlocks\n\n```vim\nlet g:PhTrimBlocks = 0\n```\n\nThis variable defines if blank lines around code blocks will be removed. Its\ndefault value is *1*.\n\n### g:PhRichTextElems\n\n```vim\nlet g:PhRichTextElems = ['bg', 'bold', 'italic']\n```\n\nThis variable defines a list of rich text elements that will be accepted for\nrendering text both in HTML and TeX formats, it is ignored when using *TOhtml*\nengine. Accepted values are *bg*, *bold*, *italic* and *underline*, other\nvalues are quietly ignored. All accepted elements are turned on by default.\nNotice that the Latex engine uses *\\colorbox* for rendering background which\nnormally has outstanding height that makes the whole line higher. To prevent\nthis, put\n\n```tex\n\\setlength\\fboxsep{1pt}\n```\n\nin the preamble of the TeX document. Script *vimhl_latex_tmpl.sh* puts this line\nin environments *Shaded*, *Framed*, and *Mdframed* automatically.\n\n### g:PhLinenrAsTblColumn\n\n```vim\nlet g:PhLinenrAsTblColumn = 1\n```\n\nDraws a line-numbered code as an HTML table. Effective only when the internal\nsyntax highlighting engine is used. Not set by default. There are a few\nvariables to control how various elements of the table will look.\n\n* *g:PhLinenrColumnBorderAttrs* defines border attributes between the\n  line-number and the code columns. Beware: it does not expect color settings,\n  see the next clause. Default value is *1px solid*.\n\n* *g:PhLinenrFgColor* defines the foreground color of the line-number column\n  and of the border between the columns. Not set by default: color of the\n  *SpecialKey* syntax highlighting group will be used in this case.\n\n* *g:PhLinenrColumnWidth* defines the line-number column width. Default value is\n  *2em*.\n\n* *g:PhLinenrColumnAttrs* defines attributes of the line-number column. Empty by\n  default. May be used to customize background color of the column.\n\n* *g:PhCodeColumnOverflowX* defines *overflow-x* behaviour of the code column.\n  Default value is *auto*. This value must correspond to non-wrapping text\n  models, otherwise line numbers may mismatch code lines if the latter wraps.\n\n* *g:PhLinenrTblBgColor* defines the background color of the table. Default\n  value is *inherit*.\n\n* *g:PhLinenrTblBorderSpacing* defines the border spacing of the table. Default\n  value is *0*.\n\n* *g:PhLinenrTblBottomPadding* defines padding on the bottom of the table.\n  Default value is *0*.\n\nBelow is an example of a stylish configuration suitable for color schemes\nwith dark background colors.\n\n```vim\nlet g:PhLinenrAsTblColumn = 1\nlet g:PhHtmlPreAttrs =\n            \\ 'style=\"white-space: pre-wrap; background: #2E3436; '.\n            \\ 'padding: 12px; font-size: 16px\"'\nlet g:PhLinenrColumnAttrs =\n            \\ 'style=\"font-size: 16px; color: #82766C; background: #2E3436\"'\nlet g:PhLinenrColumnBorderAttrs = '1px solid'\nlet g:PhLinenrColumnWidth = '2.5em'\nlet g:PhLinenrFgColor = '#204A87'\nlet g:PhLinenrTblBgColor = '#2E3436'\nlet g:PhLinenrTblBorderSpacing = '12px'\n```\n\nHighlighting shells and REPLs\n-----------------------------\n\nThe option for highlighting various shells and REPLs (bash, ghci, python REPL\netc.) is available from **version 0.10** of the plugin. Normally, one may want\nto highlight shells and REPLs blocks in a different way than code blocks. This\nis easy to achieve by specifying a variable that defines a role of the block.\nImagine that we want to use filter *vimhl* in pandoc, then the role might be\ndefined via a variable passed in the attribute *vars*:\n*vars=\"PhBlockRole=output\"*, and the block view would be customized in\n*.vimrc.pandoc* like this:\n\n```vim\nif !exists('g:PhHtmlPreAttrs')\n    let g:PhHtmlPreAttrs = 'style=\"white-space: pre-wrap; background: #FFE\"'\nendif\n\nif exists('g:PhBlockRole') \u0026\u0026 g:PhBlockRole == 'output'\n    let g:PhHtmlPreAttrs = 'style=\"white-space: pre-wrap; '.\n        \\ 'display: inline-block; border-style: none none none solid; '.\n        \\ 'border-color: blue; border-width: 15px; padding: 5px 10px\"'\n    let g:PhTexBlockStyle = 'Leftbar'\nendif\n```\n\nBut what shall we do with the highlights? There is no syntax for universal\nshell prompts and outputs. We must invent it! The plugin contains very simple\ndefinition of such a syntax in file *syntax/shelloutput.vim*. It means that the\nname for this \"language\" is *shelloutput* (you can change it via variable\n*g:PhShellOutputFt*, however it makes little sense without renaming the syntax\nfile). This filetype is magic for the plugin. It defines a *virtual prompt*:\nvalue of the variable *g:PhShellOutputPrompt* (\"||| \", i.e. *three-bars-space*\nby default). Lines that start with the virtual prompt (including blank\ncharacters before it) signal user input in the shell and are highlighted as\n*Statement* syntax items, other lines are supposed to be the shell output. The\nvirtual prompt is ignored in resulting documents because it only plays a role of\na marker for making correct highlights in the document.\n\nHighlighting shells and REPLs in TeX documents requires extra definitions in\nthe preamble because it utilizes language definition feature of Latex package\n[*Listings*](https://ctan.org/pkg/listings). Here is an example:\n\n```tex\n\\usepackage{MnSymbol}\n\\usepackage{listings}\n\\definecolor{shellpromptcolor}{HTML}{000000}\n\\definecolor{shelloutputcolor}{HTML}{666666}\n\\lstset{basicstyle=\\scriptsize\\ttfamily, breaklines=true}\n\\lstset{prebreak=\\raisebox{0ex}[0ex][0ex]\n    {\\ensuremath{\\rhookswarrow}}}\n\\lstset{postbreak=\\raisebox{0ex}[0ex][0ex]\n    {\\ensuremath{\\rcurvearrowse\\space}}}\n\\lstdefinelanguage{shelloutput}\n    {basicstyle=\\color{shelloutputcolor}\n        \\scriptsize\n        \\ttfamily\\itshape,\n     moredelim=[il][\\color{shellpromptcolor}\\upshape]{|||\\ }}\n```\n\nScript *vimhl_latex_tmpl.sh* has several options to insert these definitions\nautomatically in a pandoc template. Using these definitions has advantage of\ninserting pretty line breaks in the document automatically when they are needed.\nIf you want to set up different *also-letters* (for the notion of this, see\ndocumentation for package *Listings*) in a shell block, you can define them in\nvariable *g:PhAlsoletter*.\n\nAn example\n----------\n\n- Pandoc flavoured markdown source file *example.md*\n\n    \u003c!-- FIXME: ````pandoc highlights it mostly in blue which looks sharp --\u003e\n\n    ````\n  ### Original example from [*Pandoc User's Guide*](http://johnmacfarlane.net/pandoc/README.html#fenced-code-blocks)\n\n  ``` {#mycode .haskell .numberLines hl=\"vim\" startFrom=\"99\"}\n  qsort []     = []\n  qsort (x:xs) = qsort (filter (\u003c x) xs) ++ [x] ++\n                 qsort (filter (\u003e= x) xs)\n  ```\n\n  ### Content of my *~/.vimrc.pandoc*\n\n  ``` {#vimrc_pandoc .vim .numberLines hl=\"vim\" vars=\"PhTexBlockStyle=Mdframed\"}\n  set nocompatible\n\n  filetype off    \" filetype is set by vimhl\n\n  let g:lucius_style = 'light'\n  let g:lucius_contrast = 'high'\n  let g:lucius_contrast_bg = 'high'\n\n  colorscheme lucius\n  syntax on\n\n  if !exists('g:PhHtmlPreAttrs')\n      let g:PhHtmlPreAttrs = 'style=\"white-space: pre-wrap; background: #FFE\"'\n  endif\n\n  if exists('g:PhBlockRole') \u0026\u0026 g:PhBlockRole == 'output'\n      let g:PhHtmlPreAttrs = 'style=\"white-space: pre-wrap; '.\n              \\ 'display: inline-block; border-style: none none none solid; '.\n              \\ 'border-color: blue; border-width: 15px; padding: 5px 10px\"'\n      let g:PhTexBlockStyle = 'Leftbar'\n  endif\n\n  runtime plugin/publish_helper.vim\n\n  if exists('g:PhHtmlEngine') \u0026\u0026 g:PhHtmlEngine == 'tohtml'\n      runtime plugin/tohtml.vim\n      let g:html_no_progress = 1\n      let g:html_ignore_folding = 1\n  endif\n  ```\n\n  ### Pandoc markdown example\n\n  ``` {.pandoc .numberLines hl=\"vim\" vars=\"PhHtmlEngine=tohtml\"}\n  ### Pandoc markdown example\n\n  * Item 1\n  * Item 2\n  ```\n\n  ### List fonts in a shell\n\n  ``` {.shelloutput hl=\"vim\" vars=\"PhBlockRole=output,PhHtmlEngine=tohtml\"}\n  ||| ls Deja*\n  DejaVuSansMonoForPowerline.bdf     DejaVuSansMonoForPowerline.psfu      DejaVuSansMonoForPowerline.sfd  DejaVuSansMonoForPowerline.txt\n  DejaVuSansMonoForPowerline.bdfmap  DejaVuSansMonoForPowerline.psfu.bak  DejaVuSansMonoForPowerline.ttf  DejaVuSansMono-Powerline.otf\n  ```\n    ````\n\n- Content of *.vimrc.pandoc* (also contained in the previous listing)\n\n    ```vim\n  set nocompatible\n\n  filetype off    \" filetype is set by vimhl\n\n  let g:lucius_style = 'light'\n  let g:lucius_contrast = 'high'\n  let g:lucius_contrast_bg = 'high'\n\n  colorscheme lucius\n  syntax on\n\n  if !exists('g:PhHtmlPreAttrs')\n      let g:PhHtmlPreAttrs = 'style=\"white-space: pre-wrap; background: #FFE\"'\n  endif\n\n  if exists('g:PhBlockRole') \u0026\u0026 g:PhBlockRole == 'output'\n      let g:PhHtmlPreAttrs = 'style=\"white-space: pre-wrap; '.\n              \\ 'display: inline-block; border-style: none none none solid; '.\n              \\ 'border-color: blue; border-width: 15px; padding: 5px 10px\"'\n      let g:PhTexBlockStyle = 'Leftbar'\n  endif\n\n  runtime plugin/publish_helper.vim\n\n  if exists('g:PhHtmlEngine') \u0026\u0026 g:PhHtmlEngine == 'tohtml'\n      runtime plugin/tohtml.vim\n      let g:html_no_progress = 1\n      let g:html_ignore_folding = 1\n  endif\n    ```\n\n- Pandoc template for Latex was produced by command\n\n    ```ShellSession\n  $ bash vimhl_latex_tmpl.sh -s FFFF99 -f FF6699 -d \u003e ~/.pandoc/templates/vimhl.latex\n    ```\n\n- **HTML document (rendered in Firefox) produced by command**\n\n    ```ShellSession\n  $ pandoc --standalone -Fvimhl -o example.html example.md\n    ```\n\n----\n\n\u003cp align=\"center\"\u003e\n  \u003cimg border=\"1\" src=\"../images/images/vimhl-html.png?raw=true\" alt=\"HTML result\"/\u003e\n\u003c/p\u003e\n\n----\n\n- **Pdf document produced by command**\n\n    ```ShellSession\n  $ pandoc -Vgeometry:a4paper --template=vimhl -Fvimhl -o example.pdf example.md\n    ```\n\n----\n\n\u003cp align=\"center\"\u003e\n  \u003cimg border=\"1\" src=\"../images/images/vimhl-latex.png?raw=true\" alt=\"PDF result\"/\u003e\n\u003c/p\u003e\n\n----\n\nTrivia\n------\n\nSince April 2014 all code blocks in articles from\n[*my blog*](https://lin-techdet.blogspot.com/) are styled using *vimhl*.\n\nThanks to\n---------\n\nChristian Brabandt for plugin *Colorizer* and *Xterm2rgb* translation functions.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flyokha%2Fvim-publish-helper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flyokha%2Fvim-publish-helper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flyokha%2Fvim-publish-helper/lists"}