okken / submark

A Subset of Markdown

submark

Subset of Markdown

This project started as an example project to describe migrating from a script to a package, utilizing flit, tox, coverage, and pytest.

See http://testandcode.com/80 for the story.

Features

• Convert headings

  • # heading -> <h1> heading </h1>
  • ## heading -> <h2> heading </h2>
  • ### heading -> <h3> heading </h3>
  • #### heading -> <h4> heading </h4>
  • ##### heading -> <h5> heading </h5>

• Convert strong

  • **strong** -> <strong>strong</strong>
  • __strong__-> <strong>strong</strong>

• Convert em

  • **something** -> <em>something</em>
  • __something__-> <em>something</em>

• links

  • [message](http://some.link.html "my title")
    -> <a href="http://some.link.html" title="my title">message</a>
  • [message](http://some.link.html)
    -> <a href="http://some.link.html">message</a>

• images

  • ![alt](/some/image.png "title")'
    -> '<img src="/some/image.png" title="title"/>

• inline code

  • this is `some code`
    -> this is <code>some code</code>

• line breaks with two spaces at end of text

• horizontal rules, 3 or more dashes

  • --- -> <hr>

Usage

Use it like this:

$ submark something.md > something.html

or:

$ cat something.md | submark > something.html

or:

$ echo '**hi**' | submark
<strong>hi</strong>

Dev & Test virtual environment

Testing and development should be done with a virtual environment.

$ git clone https://github.com/okken/submark.git
$ cd submark
$ python3 -m venv venv --prompt submark
$ source venv/bin/activate
(submark) $ pip install -U pip

Testing

Testing is done with tox.

(submark) $ pip install tox
(submark) $ tox

Development

Development requires a few tools. Install submark locally and install dev tools with flit.

(submark) $ pip install flit
(submark) $ flit install --pth-file

Then you can test any changes locally with pytest.

(submark) $ pytest --cov=submark 

And when ready to test everything as an installed package:

(submark) $ tox

Building a wheel

Make sure everything is committed before running flit.

(submark) $ pip install flit
(submark) $ flit build

Yep. That's it. There should be a wheel now sitting in a dist folder.

(submark) $ ls dist
submark-0.5-py2.py3-none-any.whl
submark-0.5.tar.gz

Deploying

Flit does that too.

(submark) $ flit publish

But don't do that unless:

• You are Brian Okken

or:

• You are pointing to something other than pypi
• see https://flit.readthedocs.io/en/latest/upload.html

History

• 0.1 Initial script and tests
• 0.2 build wheel with flit
• 0.3 build and test with tox
• 0.4 move source module into a package directory
• 0.5 move tests into tests directory
• 0.6 hook up readme in toml file
• 0.7
  • flit for development with requires-extra,
  • support for links, images, inline code, line breaks, horizontal rules

submark's Issues

Add __main__.py

Hi Brian! I loved this episode. I noticed that you mentioned using cli.py and I thought I'd drop by to recommend using __main__.py so python -m submark works. I don't have time right now to submit a PR, but if that sounds too you like a good change, I totally can later.

Thanks again for the awesome podcast!

block quote support

tox python 3.7

I don't know how this should be handled, but there seems to be an implicit requirement for python 3.7 (during setup of the project):

(submark) aj@aj-XPS-L412Z:~/github/submark$ pip install tox
...
ERROR:  py37: InterpreterNotFound: python3.7

Thank's for all great stuff that you do for the community!
/AJ

code block support

hook up badges in readme

multi-level lists

like:

• this is top level
• and this
  • this a sub list
• but also numbers
  1. this could be a numbered
  2. sublist

and:

1. top could be numbers
2. like this
   • with a sub list
   • with bullets

Discussion: markdowns more able neighbour - AsciidocTor

Quite an interesting read https://www.red-gate.com/simple-talk/blogs/sundown-on-markdown/
I was a markdown partisan until I got a Asciidoc-citizen

make alt and title optional on images

The alt and title for images are supposed to be optional, but I have them required in my implementation.

Readme suggestion..

If the Testing and Development sections get flipped around so Dev is first then it is not longer an issue that tox needs flit installed before it gets run... as I discovered while following things in order!

unordered lists

test "submark something.md"

Test converting a file.

inline code blocks with double back ticks

Allow this: this is a `reasonable` code block

ordered lists

paragraphs