1Metadata-Version: 2.1 2Name: mdv 3Version: 1.7.4 4Summary: Terminal Markdown Viewer 5Home-page: http://github.com/axiros/terminal_markdown_viewer 6Author: Axiros GmbH 7Author-email: gk@axiros.com 8License: UNKNOWN 9Download-URL: http://github.com/axiros/terminal_markdown_viewer/tarball/ 10Description: # Terminal Markdown Viewer 11 12 [![Build Status][travis_img]][travis] 13 <a href='https://coveralls.io/github/axiros/terminal_markdown_viewer?branch=master'> 14 <img src='https://coveralls.io/repos/github/axiros/terminal_markdown_viewer/badge.svg?branch=master' alt='Coverage Status' /></a> 15 [![PyPI version](https://badge.fury.io/py/mdv.svg)](https://badge.fury.io/py/mdv) 16 <a href="https://github.com/ambv/black"><img alt="Code style: black" src="https://img.shields.io/badge/code%20style-black-000000.svg"></a> 17 18 19 20 21 When you edit multiple md files remotely, like in a larger 22 [mkdocs](http://www.mkdocs.org/) project, context switches between editing 23 terminal(s) and viewing browser may have some efficiency impact. 24 Also sometimes there is just no browser, like via security gateways offering 25 just a fixed set of applications on the hop in machine. 26 Further, reading efficiency and convenience is often significantly improved 27 by using colors. 28 And lastly, using such a thing for cli applications might improve user output, 29 e.g. for help texts. 30 31 This is where mdv, a Python based Markdown viewer for the terminal might be 32 a good option. 33 34 <!-- toc --> 35 36 - [Terminal Markdown Viewer](#terminal-markdown-viewer) 37 - [Features](#features) 38 - [Alternatives](#alternatives) 39 - [Installation](#installation) 40 - [Usage](#usage) 41 - [CLI](#cli) 42 - [Inline](#inline) 43 - [Sample Inline Use Case: click module docu](#sample-inline-use-case-click-module-docu) 44 - [Customization](#customization) 45 - [Screenshots](#screenshots) 46 - [TODO](#todo) 47 - [Credits](#credits) 48 - [Updates](#updates) 49 50 51 <!-- tocstop --> 52 53 54 55 If markdown is often "simple" enough to be somewhat readable on 256 color terminals (except images that is). 56 57 <img src="https://raw.githubusercontent.com/axiros/terminal_markdown_viewer/master/samples/1.png" width=500> 58 59 from 60 61 ### Source 62 # Header 1 63 ## Header 2 64 ### Header 3 65 #### Header 4 66 ##### Header 5 67 ###### Header 6 68 ```python 69 """ Test """ 70 # Make Py2 >>> Py3: 71 import os, sys; reload(sys); sys.setdefaultencoding('utf-8') 72 # no? see http://stackoverflow.com/a/29832646/4583360 ... 73 74 # code analysis for hilite: 75 try: 76 from pygments import lex, token 77 from pygments.lexers import get_lexer_by_name, guess_lexer 78 ``` 79 80 | Tables | Fmt | 81 | -- | -- | 82 | !!! hint: wrapped | 0.1 **strong** | 83 84 !!! note: title 85 this is a Note 86 87 88 You can also use mdv as a **source code** viewer, best when you have docstrings with markdown in your code: 89 90 ![](./samples/5.png) 91 92 from 93 94 ```python 95 ~/terminal_markdown_viewer $ cat setup.py 96 #!/usr/bin/env python2.7 97 # coding: utf-8 98 99 """_ 100 # Mdv installation 101 102 ## Usage 103 104 [sudo] ./setup.py install 105 106 ---- 107 """ 108 109 from setuptools import setup, find_packages 110 111 import mdv 112 113 setup( 114 name='mdv', 115 version=mdv.__version__, 116 117 ``` 118 (the '_' after the docstring telling mdv that markdown follows) 119 120 ---- 121 122 > mdv is a proof of concept hack: While for simple structures it does its job quite well, for complex markdown you want to use other tools. 123 > Especially for inlined html it simply fails. 124 125 ---- 126 127 128 ## Features 129 130 - Tons of theme combinations: mdv ships with > 200 luminocity sorted themes, converted from html themes tables to ansi. Those can be combined for code vs regular markdown output... 131 - Admonitions 132 - Tables, incl. wide table handling avoiding "interleaving" 133 - Somewhat hackable, all in [one](mdv/markdownviewer.py) module 134 - Useable as lib as well 135 - File change monitor 136 - Text wrapping 137 - Source code highlighter 138 - Little directory change monitor (cames handy when working on multiple files, to get the current one always displayed) 139 - which can run arbitrary commands on file changes 140 - which passes filepath, raw and prettyfied content to the other command 141 Note: Poor man's implementation, polling. Check inotify based tools if you want sth better. 142 143 ## Alternatives 144 145 The ones I know of (and which made me write mdv ;-) ): 146 147 1. There are quite a few from the js community (e.g. [msee](https://www.npmjs.com/package/msee), ansidown, ansimd and also nd which is great) but they require nodejs & npm, which I don't have on my servers. Also I personally wanted table handling and admonition support throughout and prob. too old to hack other peoples' js (struggling enough with my own). But have a look at them, they do some things better than mdv in this early version (I try to learn from them). Also [this](https://github.com/substack/picture-tube) would be worth a look ;-) 148 2. pandoc -> html -> elinks, lynx or pandoc -> groff -> man. (Heavy and hard to use from within other programs. Styling suboptimal) 149 3. vimcat (Also heavy and hard to use inline in other programs) 150 151 Summary: For production ready robust markdown viewing (e.g. for your customers) I recommend nd still, due to the early state of mdv. For playing around, especially with theming or when with Python, this one might be a valid alternative to look at. 152 153 ## Installation 154 155 pip install mdv 156 157 If you get `no attribute HTML_PLACEHOLDER`: update your markdown package. 158 159 [Here](https://trac.macports.org/ticket/53591) is a macport (thanks Aljaž). 160 161 162 ### Manual Install: Requirements 163 164 - python == 2.7 or > 3.5 165 - py markdown (pip install markdown) 166 - py pygments (pip install pygments) 167 - py yaml (pip install pyyaml) 168 - py docopt (pip install docopt) 169 - py tabulate (pip install tabulate) 170 171 Further a 256 color terminal (for now best with dark background) and font support for a few special separator characters (which you could change via config). 172 173 > For light terms you'd just need to revert the 5 colors from the themes, since they are sorted by luminocity. 174 175 I did not test anything on windows. 176 177 ### Manual Install: Setup 178 179 Distribution via setuptools. If setuptools is not installed, run: 180 181 pip install setuptools 182 183 184 Use the setup.py provided inside, I.e. run: 185 186 sudo ./setup.py install 187 (or ./setup.py install --user to install only for the current user) 188 189 190 191 ## Usage 192 193 ### CLI 194 195 ```markdown 196 197 # Usage: 198 199 mdv [OPTIONS] MDFILE 200 201 # Options: 202 203 MDFILE : Path to markdown file 204 -A : Strip all ansi (no colors then) 205 -C MODE : Sourcecode highlighting mode 206 -H : Print html version 207 -L : Backwards compatible shortcut for '-u i' 208 -M DIR : Monitor directory for markdown file changes 209 -T C_THEME: Theme for code highlight. If not set: Using THEME. 210 -X Lexer : Default lexer name (default: python). Set -x to use it always. 211 -b TABL : Set tab_length to sth. different than 4 [default: 4] 212 -c COLS : Fix columns to this (default: your terminal width) 213 -f FROM : Display FROM given substring of the file. 214 -h : Show help 215 -i : Show theme infos with output 216 -l : Light background (not yet supported) 217 -m : Monitor file for changes and redisplay FROM given substring 218 -n NRS : Header numbering (default: off. Say e.g. -3 or 1- or 1-5 219 -t THEME : Key within the color ansi_table.json. 'random' accepted. 220 -u STYL : Link Style (it=inline table=default, h=hide, i=inline) 221 -x : Do not try guess code lexer (guessing is a bit slow) 222 223 224 # Notes: 225 226 We use stty tool to derive terminal size. If you pipe into mdv we use 80 cols. 227 228 ## To use mdv.py as lib: 229 230 Call the main function with markdown string at hand to get a 231 formatted one back. Sorry then for no Py3 support, accepting PRs if they don't screw Py2. 232 233 ## FROM: 234 235 FROM may contain max lines to display, seperated by colon. 236 Example: 237 238 -f 'Some Head:10' -> displays 10 lines after 'Some Head' 239 240 If the substring is not found we set it to the *first* character of the file - 241 resulting in output from the top (if your terminal height can be derived correctly through the stty cmd). 242 243 ## Code Highlighting 244 245 Set -C <all|code|doc|mod> for source code highlighting of source code files. 246 Mark inline markdown with a '_' following the docstring beginnings. 247 248 - all: Show markdown docstrings AND code (default if you say, e.g. `-C.`) 249 - code: Only Code 250 - doc: Only docstrings with markdown 251 - mod: Only the module level docstring 252 253 254 ## File Monitor: 255 256 If FROM is not found we display the whole file. 257 258 ## Directory Monitor: 259 260 We check only text file changes, monitoring their size. 261 262 By default .md, .mdown, .markdown files are checked but you can change like `-M 'mydir:py,c,md,'` where the last empty substrings makes mdv also monitor any file w/o extension (like 'README'). 263 264 ### Running actions on changes: 265 266 If you append to `-M` a `'::<cmd>'` we run the command on any change detected (sync, in foreground). 267 268 The command can contain placeholders: 269 270 _fp_ # Will be replaced with filepath 271 _raw_ # Will be replaced with the base64 encoded raw content 272 of the file 273 _pretty_ # Will be replaced with the base64 encoded prettyfied output 274 275 Like: mdv -M './mydocs:py,md::open "_fp_"' which calls the open 276 command with argument the path to the changed file. 277 278 279 ## Themes 280 281 ### Theme Rollers 282 283 284 mdv -T all [file]: All available code styles on the given file. 285 mdv -t all [file]: All available md styles on the given file. 286 If file is not given we use a short sample file. 287 288 So to see all code hilite variations with a given theme: 289 290 Say C_THEME = all and fix THEME 291 292 Setting both to all will probably spin your beach ball... 293 294 ### Environ Vars 295 296 `$MDV_THEME` and `$MDV_CODE_THEME` are understood, e.g. `export 297 MDV_THEME=729.8953` in your .bashrc will give you a consistent color scheme. 298 299 300 ``` 301 302 > Regarding the strange theme ids: Those numbers are the calculated total luminocity of the 5 theme colors. 303 304 ### Inline 305 306 mdv is designed to be used well from other (Py2) programs when they have md at hand which should be displayed to the user: 307 308 ```python 309 import mdv 310 311 # config like this: 312 mdv.term_columns = 60 313 314 # calling like this (all CLI options supported, check def main 315 formatted = mdv.main(my_raw_markdown, c_theme=...) 316 ``` 317 318 > Note that I set the defaultencoding to utf-8 in ``__main__``. I have this as my default python2 setup and did not test inline usage w/o. Check [this](http://stackoverflow.com/a/29832646/4583360) for risks. 319 320 ### Sample Inline Use Case: click module docu 321 322 [Armin Ronacher](http://lucumr.pocoo.org/2014/5/12/everything-about-unicode/)'s 323 [click](http://click.pocoo.org) is a great framework for writing larger CLI apps - but its help texts are a bit boring, intended to be customized. 324 325 Here is how: 326 327 Write a normal click module with a function but w/o a doc string as shown: 328 ```python 329 @pass_context 330 def cli(ctx, action, name, host, port, user, msg): 331 """ docu from module __doc__ """ 332 ``` 333 334 On module level you provide markdown for it, like: 335 336 ```shell 337 ~/axc/plugins/zodb_sub $ cat zodb.py | head 338 """ 339 # Fetch and push ZODB trees 340 341 ## ACTION: < info | pull | push | merge | dump | serve> 342 343 - info: Requests server availability information 344 (...) 345 ``` 346 which you set at click module import time: 347 348 mod.cli.help = mod.__doc__ 349 350 351 Lastly do this in your app module: 352 353 ```python 354 from click.formatting import HelpFormatter 355 def write_text(self, text): 356 """ since for markdown pretty out on cli I found no good tool 357 so I built my own """ 358 # poor man's md detection: 359 if not text.strip().startswith('#'): 360 return orig_write_text(self, text) 361 from axc.markdown.mdv import main as mdv 362 self.buffer.append(mdv(md=text, theme=os.environ['AXC_THEME'])) 363 364 HelpFormatter.orig_write_text = HelpFormatter.write_text 365 HelpFormatter.write_text = write_text 366 ``` 367 368 The output has then colors: 369 370 ![](samples/3.png) 371 372 and at smaller terms rewraps nicely: 373 374 ![](samples/4.png) 375 376 Further, having markdown in the module ``__doc__`` makes it simple to add into a global project docu framework, like mkdocs. 377 378 379 380 ## Customization 381 382 You can supply all CLI args in `$HOME/.mdv`, in yaml format. 383 384 More flex you have via `$HOME/.mdv.py`, which is execed if present, when 385 running `main`. 386 387 Alternatively, in [mdv.py](mdv.py) you can change some config straight forward. 388 389 ```python 390 # ---------------------------------------------------------------------- Config 391 txt_block_cut, code_pref, list_pref, br_ends = '✂', '| ', '- ', '◈' 392 # ansi cols (default): 393 # R: Red (warnings), L: low visi, BG: background, BGL: background light, C=code 394 # H1 - H5 = the theme, the numbers are the ansi color codes: 395 H1, H2, H3, H4, H5, R, L, BG, BGL, T, TL, C = \ 396 231, 153, 117, 109, 65, 124, 59, 16, 188, 188, 59, 102 397 # Code (C is fallback if we have no lexer). Default: Same theme: 398 CH1, CH2, CH3, CH4, CH5 = H1, H2, H3, H4, H5 399 400 code_hl = { "Keyword" : 'CH3', "Name" : 'CH1', 401 "Comment" : 'L', "String": 'CH4', 402 "Error" : 'R', "Number": 'CH4', 403 "Operator": 'CH5', 404 "Generic" : 'CH2' 405 } 406 407 admons = {'note' : 'H3', 'warning': 'R', 408 'attention': 'H1', 'hint' : 'H4', 409 'summary' : 'H1', 'hint' : 'H4', 410 'question' : 'H5', 'danger' : 'R', 411 'caution' : 'H2' 412 } 413 414 def_lexer = 'python' 415 guess_lexer = True 416 # also global. but not in use, BG handling can get pretty involved... 417 background = BG 418 419 # normal text color: 420 color = T 421 422 show_links = None 423 424 # could be given, otherwise read from ansi_tables.json: 425 themes = {} 426 427 428 # sample for the theme roller feature: 429 md_sample = '' 430 431 # ------------------------------------------------------------------ End Config 432 ``` 433 434 Any importing module can overwrite those module global variables as well. 435 436 Should you need yet additional themes, add them to ``ansi_tables.json`` file by adding your ansi codes there. 437 438 439 440 ## Screenshots 441 442 Random results, using the theme roller feature: 443 444 ![second](https://github.com/axiros/terminal_markdown_viewer/blob/master/samples/2.png) 445 446 Note the table block splitting when the table does not fit (last picture). 447 448 ## TODO 449 450 - Refactor the implementation, using a config class 451 - Lines separators not optimal ([nd](https://www.npmjs.com/package/nd) does better) 452 - Test light colorscheme 453 - Dimming 454 - A few grey scale and 8 color themes 455 - Sorting of the json by luminance 456 - Some themes have black as darkest color, change to dark grey 457 - Common Mark instead of markdown 458 459 ## PerfTests 460 461 Rendering this readme [100 times](./mdv/misc/perftest.py): 462 ``` 463 black root@ip-10-34-2-19:~/terminal_markdown_viewer/mdv/misc# python perfest.py 464 0.03 paka 465 0.04 paka_breaks 466 0.04 paka_xml 467 1.47 mistletoe 468 8.70 markdown 469 5.22 commonmark 470 ``` 471 - markdown did better than commonmark w/o extensions but table and fenced code 472 are definitelly required for 99% users. 473 474 - paka is a wrapper around the C reference lib -> requires compilation. 475 476 - mistletoe is pure python, crazy that they are so much faster than CommonMark. 477 They say in pypy they are speed up even much more. 478 479 mistletoe downside: py2 only via a fork. 480 481 482 ## Credits 483 484 [pygments](http://pygments.org/) (using their lexer) 485 486 [tabulate](https://pypi.python.org/pypi/tabulate) 487 488 and, naturally, the [python markdown project](https://pythonhosted.org/Markdown/authors.html) 489 490 Update: Next version will be CommonMark based though... 491 492 493 ## Updates 494 495 ### July 2016: 496 497 Sort of an excuse for the long long time w/o an update: 498 I did actually start working on a more solid version based on CommonMark but 499 that went a bit out of scope, into a general html terminal viewer, which will 500 probably never be finished :-/ 501 502 So at least here an update containing the stuff you guys sent as PRs, thanks all!! 503 504 - installation and dependencies via a setup.py (thanks 505 [Martin](https://github.com/althonos)) 506 - supporting `echo -e "# foo\n## bar" | mdv -` and a 'light' theme (thanks 507 [Stanislav](https://github.com/seletskiy)) 508 - and a few other improvements regarding python2.7, file location and pyyaml, thanks all. 509 510 Also: 511 512 - fixed the most obvious bugs with nested ordered and unordered lists 513 - fixed bold marker 514 - different color highlighting for the list markers 515 - added a source code highlighting mode, which highlights also docstrings in markdown (`-C <mode>`) 516 - some tests in the tests folder 517 - using `textwrap` now for the wrapping, to avoid these word breaks a few complained about 518 - you can supply the default lexer now, e.g. `-X javascript [-x]` 519 - fixed but with not rendered strong texts 520 - pip install mdv 521 522 523 ### Nov 2016: 524 525 - travis 526 527 - Inline link tables 528 529 ![](samples/links.png) 530 531 532 533 [travis]: https://travis-ci.org/axiros/terminal_markdown_viewer 534 [travis_img]: https://travis-ci.org/axiros/terminal_markdown_viewer.svg?branch=master 535 536 537 538 ### Sept 2018: 539 540 - Merged some PRs. 541 - Decent [code formatter](https://github.com/ambv/black). Not that this weekend hack got more readable though. Well, maybe a bit. 542 - Revised Py3 support (finally found peace with it, since they enforce UTF-8 everywhere the new features begin to outweigh the nightmares of trying to decode everything without need). 543 - Indented code in PY3 was broken, fixed that. *Why, PY3, are you you creating crap like "b'foo'" instead raising or auto-decoding?* 544 - Header numbering feature added (`-n 2-4` or `-n 1-`) 545 <img src="https://raw.githubusercontent.com/axiros/terminal_markdown_viewer/master/samples/header_num.png" width="400"/> 546 547Keywords: markdown,markup,terminal,hilighting,syntax,source code 548Platform: UNKNOWN 549Classifier: Programming Language :: Python 550Classifier: Natural Language :: English 551Classifier: Operating System :: POSIX 552Classifier: Topic :: Text Processing :: Markup 553Classifier: License :: OSI Approved :: BSD License 554Classifier: Programming Language :: Python :: 2.7 555Classifier: Programming Language :: Python :: 3.6 556Classifier: Programming Language :: Python :: 3.7 557Description-Content-Type: text/markdown 558Provides-Extra: yaml 559