{"id":20957219,"url":"https://github.com/axiros/mdvl","last_synced_at":"2025-05-14T05:32:47.852Z","repository":{"id":22571258,"uuid":"96714437","full_name":"axiros/mdvl","owner":"axiros","description":"Lightweight markdown terminal renderer","archived":false,"fork":false,"pushed_at":"2022-01-28T21:02:21.000Z","size":1365,"stargazers_count":54,"open_issues_count":3,"forks_count":7,"subscribers_count":9,"default_branch":"master","last_synced_at":"2024-11-04T04:07:07.291Z","etag":null,"topics":["markdown-parser","markdown-viewer","terminal","terminal-app","terminal-colors"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/axiros.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-07-09T22:12:46.000Z","updated_at":"2024-01-03T14:14:59.000Z","dependencies_parsed_at":"2022-08-07T10:15:53.609Z","dependency_job_id":null,"html_url":"https://github.com/axiros/mdvl","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/axiros%2Fmdvl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/axiros%2Fmdvl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/axiros%2Fmdvl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/axiros%2Fmdvl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/axiros","download_url":"https://codeload.github.com/axiros/mdvl/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225277874,"owners_count":17448762,"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":["markdown-parser","markdown-viewer","terminal","terminal-app","terminal-colors"],"created_at":"2024-11-19T01:30:10.796Z","updated_at":"2024-11-19T01:30:11.947Z","avatar_url":"https://github.com/axiros.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Light Markdown Renderer\n\n\n[![Build Status][travis_img]][travis]\n\nDependency free renderer for a subset of markdown to the terminal\n- w/o going via HTML (i.e. no html markup support)\n- sloc (w/o comments) around 100, i.e. adaptable, extendable\n\n\u003e This one is intended soleley to hilite somewhat \"lightly\" structured text\nreasonably swift. Ideal for highlighting doc strings or CLI command help, where you\ndon't want to install markdown libs to do that first - e.g. in new containers.\n\nIn no way this is useable as a full markdown document viewer, alone for the\nmissing html support.\n\nA real use case are bash scripts, where you repeatedly want to output formatted stuff, e.g. in a loop.\nThen, a very lightweight tool (short startup time for the python process)\nis desirable.\nNote: There [are](https://github.com/chadbraunduin/markdown.bash)\n unix standard tool based renderers around, with good results, check them out\n (and if only to see how awesome `sed` really is...).\nThey did not work for me for some output related problems - but they might for you.\n\nOriginally the script was within a Here Document within bash scripts but this\nversion would be also useable inline in a python programs. Thats why some\noverhead for config mgmt is present - for a version embedded in e.g. a bash\nscript you would only need the main function and replace the `C.\u003ccolor\u003e` with\nthe shell eviron vars, e.g. `C.H1` -\u003e `$H1`\n\n\n# Design\n\nWe assume the soure *is* already formatted with care and\nmdvl's main jobs are the coloring and the wrapping. Meaning that the source is\nformatted to be readable in environments w/o coloring and structure aware wrapping,\nspecifically docstrings in source code editors.\n\nSpecifically this refers to the author using the markdown link reference feature\ninstead of spamming the source with long urls.  \nSeel also the handling of linespacing, below.\n\n\n# Usage\n\n## Inline\n\n    mdvl(source_markdown, **config)\n\n## Pipe\n\n    cat README.md | ./mdvl.py\n\n## Standalone\n\n```\n./mdv.py '''# Hello'''\n./mdv.py README.md\n```\n\n## Shebang Problem\n\nWe use `#!/usr/bin/env python -Ss` as shebang - which is not POSIX I had to [learn](https://stackoverflow.com/questions/4303128/how-to-use-multiple-arguments-with-a-shebang-i-e), after seeing it fail on some Linuxes. Workaround is to call mdvl.py through an alias like `python -Ss mdvl.py`.\n\n\n# 'Installation'\n\n    wget -q https://raw.githubusercontent.com/axiros/mdvl/master/mdvl.py\n\nYes, that url supports version pinning.\n\nIf you absolutely feel better with 10 files instead of one then do:\n\n    pip[3] install mdvl\n\n\u003e Remember: This is not a very feature rich renderer. If you anyway already have pip on the system you want a real viewer, e.g. mdv.\n\n\n\n# Configuration / Features\n\nRestricted set of md. This readme pretty much has them all in.\n\nThis is how the default output looks with default config.\n![](./img/default.png)\n\nCheck attributes of classes [`Facts`][1] and [`Colors`][2].\nThose you can deliver as kw args or via environ. e.g.:\n\n```\nset -a; H1=171; H2=54; term_width=50; header_numbering=-1; set +a\n./mdvl.py README.md\n```\n\n\n## Worth mentioning\n\n### Blockquotes\n\n\u003e Blockquotes\n\u003e\u003e - in different levels\n\u003e\u003e - with lists\n\n### Fenced Code or Indented Code\n\n    fenced code - or indented code\n    w/o syntax highlighting though\n\n### Line Spacing\nWe stay closer to the source document than a real md renderer would, e.g. we\n*keep* all linebreaks between two textblocks.\nIntra textblock rendering is working like the standard, i.e. 2 spaces denote a linesep, else we wrap according to available columns.\n\n\n\n## Questionable Features ;-)\n\n*Header Auto Numbering* Set this parameter to a min. number of lines of\nmarkdown sources (-1 to switch feature off). When source document has more\nlines than this we'll autonumber the headers.\n\n*Light \"Tables\"* Non standard - but somewhat handy for documenting e.g.\nCLI Params of a command:\nWhen first word of a line is starred, we set a starting indent for the\nsubsequent lines of that textblock to the length of that first word.\nSee rendering of this paragraph in `mdvl`.\nThat way you get an easy table-like presentation of lists with keywords,\nwhich look good also in the source. See the screenshot of the rendered readme for a visual example.\nIf you don't need it, switch it off via `no_smart_indent=True`.\n\n*Options List* Non standard as well. Formats lines like   \n\n-a: Option A  \n-b: Option B  \n\nnicely, i.e. with indented line wrapping and markup of the first word.\nTrigger is that the first word of a line startswith '-', endswith ':'.\nYou can overwrite the triggers via `opts_tbl_start` and `opts_tbl_end` (which you\nmight want to use to switch that feature off).\n\n\u003e we do not require two spaces for such options lists to line break. Add them\n\u003e if you render in standard renderers or preprocess them.\n\n![](./img/opts_src.png)\n![](./img/opts_res.png)\n\n\n*Horizontal Rules* CommonMark allows to use 3 \"-\", \"_\" or star. We assign\ndifferent colors to them, see rendering of this README with `mdvl`.\n\n*Indents* configure `indent` and/or `width` and/or `rindent` (\"r\" for right) to get the output indented\nThat feature comes handy if you want to nest to markdown sources, i.g. module\ndoc and function doc. ![](./img/indent.png)\n\n*Single Line Handling* No leading line breaks, enables to use markdown within\n surrounding text.\n\n\n## Bugs\n\nKnown and severe one is the problem of solicitated star characters. We\ncurrently can't detect them, the renderer assumes it is the beginning of an\nitalic format and resets only at the next textblock :-(\n\n\n\n## Py2 / Py3\n\nThe thing runs in Python2 and Python3 - for the frequent rendering use case you\nwant Python 2:\n\n```\n# python -m timeit \"import os; os.system('python -c \\\"i=1\\\"')\"\n100 loops, best of 3: 10 msec per loop\n# python -m timeit \"import os; os.system('python3 -c \\\"i=1\\\"')\"\n100 loops, best of 3: 18.1 msec per loop\n# python -m timeit \"import os; os.system('python -Ssc \\\"i=1\\\"')\"\n100 loops, best of 3: 4.2 msec per loop\n# python -m timeit \"import os; os.system('python3 -Ssc \\\"i=1\\\"')\"\n100 loops, best of 3: 10.6 msec per loop\n```\n\n****\n____\n----\n\nThats all - and demonstrates the horizontal rules ;-)\n\n\n[1]: https://github.com/axiros/mdvl/blob/master/mdvl.py#L61\n[2]: https://github.com/axiros/mdvl/blob/master/mdvl.py#L30\n[travis_img]: https://travis-ci.org/axiros/mdvl.svg?branch=master\n[travis]:     https://travis-ci.org/axiros/mdvl\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faxiros%2Fmdvl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faxiros%2Fmdvl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faxiros%2Fmdvl/lists"}